diff options
| author | Hasan Wan <hasan.wan@intel.com> | 2012-05-25 16:47:13 +0800 |
|---|---|---|
| committer | Hasan Wan <hasan.wan@intel.com> | 2012-05-28 16:06:22 +0800 |
| commit | 1ddee039e66b9c1feb2129a1904e60760e0e8fc3 (patch) | |
| tree | 84a3b12d0f839c6a2ef702eb02f3288c91cf5902 /docs/reference | |
| parent | f7d643cbb2184346b6f8d26091eb7eb38c6bbfe1 (diff) | |
| download | pygobject2-1ddee039e66b9c1feb2129a1904e60760e0e8fc3.tar.gz pygobject2-1ddee039e66b9c1feb2129a1904e60760e0e8fc3.tar.bz2 pygobject2-1ddee039e66b9c1feb2129a1904e60760e0e8fc3.zip | |
Updated with Tizen:Base source codes
Diffstat (limited to 'docs/reference')
55 files changed, 23353 insertions, 0 deletions
diff --git a/docs/reference/entities.docbook.in b/docs/reference/entities.docbook.in new file mode 100644 index 0000000..be788f8 --- /dev/null +++ b/docs/reference/entities.docbook.in @@ -0,0 +1 @@ +<!ENTITY version "@PACKAGE_VERSION@"> diff --git a/docs/reference/pygio-appinfo.xml b/docs/reference/pygio-appinfo.xml new file mode 100644 index 0000000..eaeb060 --- /dev/null +++ b/docs/reference/pygio-appinfo.xml @@ -0,0 +1,894 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioappinfo"> + <refnamediv> + <refname>gio.AppInfo</refname> + <refpurpose>Information about an installed application and methods to launch it (with file arguments).</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.AppInfo</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-gioappinfo">gio.AppInfo</link></methodname> + <methodparam><parameter role="keyword">commandline</parameter></methodparam> + <methodparam><parameter role="keyword">application_name</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.APP_INFO_CREATE_NONE</initializer></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--add-supports-type">add_supports_type</link></methodname> + <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> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--equal">equal</link></methodname> + <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> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--get-executable">get_executable</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--get-id">get_id</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--get-name">get_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--launch">launch</link></methodname> + <methodparam><parameter role="keyword">files</parameter></methodparam> + <methodparam><parameter role="keyword">launch_context</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--launch-uris">launch_uris</link></methodname> + <methodparam><parameter role="keyword">uris</parameter></methodparam> + <methodparam><parameter role="keyword">launch_context</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--remove-supports-type">remove_supports_type</link></methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--set-as-default-for-extension">set_as_default_for_extension</link></methodname> + <methodparam><parameter role="keyword">extension</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--set-as-default-for-type">set_as_default_for_type</link></methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--should-show">should_show</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--supports-files">supports_files</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioappinfo--supports-uris">supports_uris</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--app-info-get-all">gio.app_info_get_all</link></methodname> + <methodparam></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--app-info-get-all-for-type">gio.app_info_get_all_for_type</link></methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--app-info-get-default-for-type">gio.app_info_get_default_for_type</link></methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + <methodparam><parameter role="keyword">must_support_uris</parameter></methodparam> +</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> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioappinfo">gio.AppInfo</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> is implemented by + <link linkend="class-giodesktopappinfo"><classname>gio.DesktopAppInfo</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + and <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link> + are used for describing and launching applications installed on the system. + </para> + <para> + As of GLib 2.20, URIs will always be converted to POSIX paths (using + <methodname><link linkend="method-giofile--get-path">gio.File.get_path</link></methodname>()) when using + <methodname><link linkend="method-gioappinfo--launch">gio.AppInfo.launch</link></methodname>() + even if the application requested an URI and not a POSIX path. For example for an desktop-file + based application with Exec key totem %U and a single URI, sftp://foo/file.avi, then /home/user/.gvfs/sftp + on foo/file.avi will be passed. This will only work if a set of suitable GIO extensions (such as gvfs 2.26 + compiled with FUSE support), is available and operational; if this is not the case, the URI will be passed + unmodified to the application. Some URIs, such as mailto:, of course cannot be mapped to a POSIX path + (in gvfs there's no FUSE mount for it); such URIs will be passed unmodified to the application. + </para> + <para> + Specifically for gvfs 2.26 and later, the POSIX URI will be mapped back to the GIO URI in the + <link linkend="class-giofile"><classname>gio.File</classname></link> constructors + (since gvfs implements the GVfs extension point). As such, if the application needs to examine the URI, + it needs to use + <methodname><link linkend="method-giofile--get-uri">gio.File.get_uri</link></methodname>() + or similar on + <link linkend="class-giofile"><classname>gio.File</classname></link>. + In other words, an application cannot assume that the URI passed to e.g. + <methodname><link linkend="constructor-giofile">gio.File</link></methodname>() constructor + is equal to the result of + <methodname><link linkend="method-giofile--get-uri">gio.File.get_uri</link></methodname>(). + </para> + </refsect1> + + <refsect1 id="constructor-gioappinfo"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.AppInfo</methodname> + <methodparam><parameter role="keyword">commandline</parameter></methodparam> + <methodparam><parameter role="keyword">application_name</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.APP_INFO_CREATE_NONE</initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>commandline</parameter> :</term> + <listitem><simpara>the commandline to use + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>application_name</parameter> :</term> + <listitem><simpara>the application name, or <literal>None</literal> to use commandline. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>flags that can specify details of the created, + from <xref linkend="gio-app-info-constants" endterm="gio-app-info-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + for given command. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + from the given information. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioappinfo--add-supports-type"> + <title>gio.AppInfo.add_supports_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>add_supports_type</methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>content_type</parameter> :</term> + <listitem><simpara>A string.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>add_supports_type</methodname>() method adds a content type + to the application information to indicate the application is capable of + opening files with the given content type. + </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> + + <programlisting><methodsynopsis language="python"> + <methodname>can_remove_supports_type</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if it is possible to remove + supported content types from a given appinfo, <literal>False</literal> + if not. </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_remove_supports_type</methodname>() method checks if a + supported content type can be removed from an application. + </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> + + <programlisting><methodsynopsis language="python"> + <methodname>dup</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A duplicate of appinfo.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>dup</methodname>() method creates a duplicate of a + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--equal"> + <title>gio.AppInfo.equal</title> + + <programlisting><methodsynopsis language="python"> + <methodname>equal</methodname> + <methodparam><parameter role="keyword">icon2</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>appinfo2</parameter> :</term> + <listitem><simpara>the second + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if appinfo1 is equal to appinfo2. + <literal>False</literal> otherwise.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>equal</methodname>() method checks if two + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>s are equal. + </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> + + <programlisting><methodsynopsis language="python"> + <methodname>get_description</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A string containing a description of the application + appinfo, or <literal>None</literal> if none.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_description</methodname>() method gets a human-readable + description of an installed application. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--get-executable"> + <title>gio.AppInfo.get_executable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_executable</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the appinfo's application + binary's name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_description</methodname>() method gets the executable's + name for the installed application. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--get-icon"> + <title>gio.AppInfo.get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_icon</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the default + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> for appinfo. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_icon</methodname>() method gets the icon for the application. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--get-id"> + <title>gio.AppInfo.get_id</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_id</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the application's ID. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_id</methodname>() method gets the ID of an application. + An id is a string that identifies the application. The exact format of the + id is platform dependent. For instance, on Unix this is the desktop file id + from the xdg menu specification. + </para> + <para> + Note that the returned ID may be <literal>None</literal>, depending on + how the appinfo has been constructed. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--get-name"> + <title>gio.AppInfo.get_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the name of the application for appinfo. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_name</methodname>() method gets the installed + name of the application. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--launch"> + <title>gio.AppInfo.launch</title> + + <programlisting><methodsynopsis language="python"> + <methodname>launch</methodname> + <methodparam><parameter role="keyword">files</parameter></methodparam> + <methodparam><parameter role="keyword">launch_context</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>files</parameter> :</term> + <listitem><simpara>a list of <link linkend="class-giofile"><classname>gio.File</classname></link> objects. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>launch_context</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link> + or <literal>None</literal>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on successful launch, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>launch</methodname>() method launches the application. + Passes files to the launched application as arguments, using the optional + launch_context to get information about the details of the launcher + (like what screen it is on). On error, error will be set accordingly. + </para> + <para> + To lauch the application without arguments pass a <literal>None</literal> for files list. + </para> + <para> + Note that even if the launch is successful the application launched can fail + to start if it runs into problems during startup. There is no way to detect this. + </para> + <para> + Some URIs can be changed when passed through a + <link linkend="class-giofile"><classname>gio.File</classname></link> + (for instance unsupported uris with strange formats like mailto:), so + if you have a textual uri you want to pass in as argument, consider using + <methodname><link linkend="method-gioappinfo--launch-uris">gio.File.launch_uris</link></methodname>() + instead. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--launch-uris"> + <title>gio.AppInfo.launch_uris</title> + + <programlisting><methodsynopsis language="python"> + <methodname>launch_uris</methodname> + <methodparam><parameter role="keyword">uris</parameter></methodparam> + <methodparam><parameter role="keyword">launch_context</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>uris</parameter> :</term> + <listitem><simpara>a list containing URIs to launch. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>launch_context</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link> + or <literal>None</literal>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on successful launch, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>launch_uris</methodname>() method launches the application. + Passes uris to the launched application as arguments, using the optional + launch_context to get information about the details of the launcher + (like what screen it is on). On error, error will be set accordingly. + </para> + <para> + To lauch the application without arguments pass a <literal>None</literal> for files list. + </para> + <para> + Note that even if the launch is successful the application launched can fail + to start if it runs into problems during startup. There is no way to detect this. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--remove-supports-type"> + <title>gio.AppInfo.remove_supports_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>remove_supports_type</methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>content_type</parameter> :</term> + <listitem><simpara>A string.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>remove_supports_type</methodname>() method removes a + supported type from an application, if possible. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--set-as-default-for-extension"> + <title>gio.AppInfo.set_as_default_for_extension</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_as_default_for_extension</methodname> + <methodparam><parameter role="keyword">extension</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>extension</parameter> :</term> + <listitem><simpara>A string containing the file extension (without the dot). + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_as_default_for_extension</methodname>() method sets the + application as the default handler for the given file extention. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--set-as-default-for-type"> + <title>gio.AppInfo.set_as_default_for_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_as_default_for_type</methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>content_type</parameter> :</term> + <listitem><simpara>The content type. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_as_default_for_type</methodname>() method sets the + application as the default handler for a given type. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--should-show"> + <title>gio.AppInfo.should_show</title> + + <programlisting><methodsynopsis language="python"> + <methodname>should_show</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the appinfo should be shown, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>should_show</methodname>() method checks if the application + info should be shown in menus that list available applications. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--supports-files"> + <title>gio.AppInfo.supports_files</title> + + <programlisting><methodsynopsis language="python"> + <methodname>supports_files</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the appinfo supports files. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>supports_files</methodname>() method checks if the application + accepts files as arguments. + </para> + </refsect2> + + <refsect2 id="method-gioappinfo--supports-uris"> + <title>gio.AppInfo.supports_uris</title> + + <programlisting><methodsynopsis language="python"> + <methodname>supports_uris</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the appinfo supports uris. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>supports_uris</methodname>() method checks if the application + accepts uris as arguments. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--app-info-get-all"> + <title>gio.app_info_get_all</title> + + <programlisting><methodsynopsis language="python"> + <methodname>app_info_get_all</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list of <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>s. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>app_info_get_all</methodname>() function gets a list of all of + the applications currently registered on this system. + </para> + <para> + For desktop files, this includes applications that have NoDisplay=true set or are + excluded from display by means of OnlyShowIn or NotShowIn. See + <methodname><link linkend="method-gioappinfo--should-show">gio.AppInfo.should_show</link></methodname>(). + The returned list does not include applications which have the Hidden key set. + </para> + </refsect2> + + <refsect2 id="function-gio--app-info-get-all-for-type"> + <title>gio.app_info_get_all_for_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>app_info_get_all_for_type</methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>content_type</parameter> :</term> + <listitem><simpara>the content type to find a + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + for.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list of <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>s + for a given content type or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>app_info_get_all_for_type</methodname>() function gets a list of all + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link>s + for a given content type. + </para> + </refsect2> + + <refsect2 id="function-gio--app-info-get-default-for-type"> + <title>gio.app_info_get_default_for_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>app_info_get_default_for_type</methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + <methodparam><parameter role="keyword">must_support_uris</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>content_type</parameter> :</term> + <listitem><simpara>the content type to find a + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + for.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>must_support_uris</parameter> :</term> + <listitem><simpara>if <literal>True</literal>, the + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + is expected to support URIs </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + for given content_type or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>app_info_get_default_for_type</methodname>() function gets the + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + that correspond to a given content type. + </para> + </refsect2> + + <refsect2 id="function-gio--app-info-get-default-for-uri-scheme"> + <title>gio.app_info_get_default_for_uri_scheme</title> + + <programlisting><methodsynopsis language="python"> + <methodname>app_info_get_default_for_uri_scheme</methodname> + <methodparam><parameter role="keyword">uri_scheme</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>uri_scheme</parameter> :</term> + <listitem><simpara>a string containing a URI scheme.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + for given uri_scheme or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>app_info_get_default_for_uri_scheme</methodname>() function gets + the default application for launching applications using this URI scheme. A URI + scheme is the initial part of the URI, up to but not including the + ':', 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-applaunchcontext.xml b/docs/reference/pygio-applaunchcontext.xml new file mode 100644 index 0000000..66bb229 --- /dev/null +++ b/docs/reference/pygio-applaunchcontext.xml @@ -0,0 +1,194 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioapplaunchcontext"> + <refnamediv> + <refname>gio.AppLaunchContext</refname> + <refpurpose>Application launch context.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.AppLaunchContext</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-gioapplaunchcontext">gio.AppLaunchContext</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioapplaunchcontext--get-display">get_display</link></methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">files</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioapplaunchcontext--get-startup-notify-id">get_startup_notify_id</link></methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">files</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioapplaunchcontext--launch-failed">launch_failed</link></methodname> + <methodparam><parameter role="keyword">startup_notify_id</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioapplaunchcontext">gio.AppLaunchContext</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link> + is used for integrating the launch with the launching application. This is used to handle for + instance startup notification and launching the new application on the same screen as the launching window. + </para> + </refsect1> + + <refsect1 id="constructor-gioapplaunchcontext"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.AppLaunchContext</methodname> + <methodparam></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-gioapplaunchcontext"><classname>gio.AppLaunchContext</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new application launch context. This is not normally used, instead + you instantiate a subclass of this, such as + <link linkend="class-gdkapplaunchcontext"><classname>gtk.gdk.AppLaunchContext</classname></link>. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioapplaunchcontext--get-display"> + <title>gio.AppLaunchContext.get_display</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_display</methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">files</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>info</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>files</parameter> :</term> + <listitem><simpara>a list of + <link linkend="class-giofile"><classname>gio.File</classname></link> + objects.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a display string for the display. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_display</methodname>() method gets the display + string for the display. This is used to ensure new applications + are started on the same display as the launching application. + </para> + </refsect2> + + <refsect2 id="method-gioapplaunchcontext--get-startup-notify-id"> + <title>gio.AppLaunchContext.get_startup_notify_id</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_startup_notify_id</methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">files</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>info</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>files</parameter> :</term> + <listitem><simpara>a list of + <link linkend="class-giofile"><classname>gio.File</classname></link> + objects.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a startup notification ID for the application, + or <literal>None</literal> if not supported. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_startup_notify_id</methodname>() method initiates + startup notification for the application and returns the DESKTOP_STARTUP_ID + for the launched operation, if supported. + </para> + <para> + Startup notification IDs are defined in the FreeDesktop.Org Startup Notifications standard. + </para> + </refsect2> + + <refsect2 id="method-gioapplaunchcontext--launch-failed"> + <title>gio.AppLaunchContext.launch_failed</title> + + <programlisting><methodsynopsis language="python"> + <methodname>launch_failed</methodname> + <methodparam><parameter role="keyword">startup_notify_id</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>startup_notify_id</parameter> :</term> + <listitem><simpara>the startup notification id that was returned by + <methodname><link linkend="method-gioapplaunchcontext--get-startup-notify-id">get_startup_notify_id</link></methodname>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a startup notification ID for the application, + or <literal>None</literal> if not supported. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_startup_notify_id</methodname>() method is called + when an application has failed to launch, so that it can cancel the application + startup notification started in + <methodname><link linkend="method-gioapplaunchcontext--get-startup-notify-id">get_startup_notify_id</link></methodname> + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-asyncresult.xml b/docs/reference/pygio-asyncresult.xml new file mode 100644 index 0000000..abe56ce --- /dev/null +++ b/docs/reference/pygio-asyncresult.xml @@ -0,0 +1,117 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioasyncresult"> + <refnamediv> + <refname>gio.AsyncResult</refname> + <refpurpose>Asynchronous Function Results.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.AsyncResult</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioasyncresult--get-source-object">get_source_object</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioasyncresult">gio.AsyncResult</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> is required by + <link linkend="class-gobject"><classname>gobject.GObject</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> is implemented by + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + provides a base class for implementing asynchronous function results. + </para> + <para> + Asynchronous operations are broken up into two separate operations which are chained + together by a GAsyncReadyCallback. To begin an asynchronous operation, provide a + GAsyncReadyCallback to the asynchronous function. This callback will be triggered when + the operation has completed, and will be passed a GAsyncResult instance filled with the + details of the operation's success or failure, the object the asynchronous function was + started for and any error codes returned. The asynchronous callback function is then expected + to call the corresponding "_finish()" function with the object the function was called for, + and the <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + instance, and optionally, an error to grab any error conditions that may have occurred. + </para> + <para> + The purpose of the "_finish()" function is to take the generic result of type GAsyncResult and + return the specific result that the operation in question yields (e.g. a + <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + for a "enumerate children" operation). If the result or error status of the operation is not needed, + there is no need to call the "_finish()" function, GIO will take care of cleaning up the result and error + information after the GAsyncReadyCallback returns. It is also allowed to take a reference to the + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + and call "_finish()" later. + </para> + <para> + The callback for an asynchronous operation is called only once, and is always called, even + in the case of a cancelled operation. On cancellation the result is a gio.ERROR_CANCELLED error. + </para> + <para> + Some ascynchronous operations are implemented using synchronous calls. These are run in a + separate thread, if GThread has been initialized, but otherwise they are sent to the Main Event + Loop and processed in an idle function. So, if you truly need asynchronous operations, make + sure to initialize GThread. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioasyncresult--get-source-object"> + <title>gio.AsyncResult.get_source_object</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_source_object</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the source object for the res. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_source_object</methodname>() method gets the source object + from a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-bufferedinputstream.xml b/docs/reference/pygio-bufferedinputstream.xml new file mode 100644 index 0000000..677b1da --- /dev/null +++ b/docs/reference/pygio-bufferedinputstream.xml @@ -0,0 +1,461 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giobufferedinputstream"> + <refnamediv> + <refname>gio.BufferedInputStream</refname> + <refpurpose>Buffered Input Stream</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.BufferedInputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giofilterinputstream">gio.FilterInputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giobufferedinputstream">gio.BufferedInputStream</link></methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--fill">fill</link></methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--fill-async">fill_async</link></methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--fill-finish">fill_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--get-available">get_available</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--get-buffer-size">get_buffer_size</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--read-byte">read_byte</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedinputstream--set-buffer-size">set_buffer_size</link></methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--buffered-input-stream-new-sized">gio.buffered_input_stream_new_sized</link></methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> + +-- <link linkend="class-giofilterinputstream">gio.FilterInputStream</link> + +-- <link linkend="class-giobufferedinputstream">gio.BufferedInputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giobufferedinputstream"> + <title>gio.BufferedInputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"buffer-size"</entry> + <entry>Read - Write - Construct</entry> + <entry>The size of the backend buffer. Allowed values: >= 1. Default value: 4096.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link> + implements <link linkend="class-giofilterinputstream"><classname>gio.FilterInputStream</classname></link> + and provides for buffered reads. + </para> + <para> + By default, + <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link>'s + buffer size is set at 4 kilobytes. + </para> + <para> + To create a buffered input stream, use + <methodname><link linkend="constructor-giobufferedinputstream">gio.BufferedInputStream</link></methodname>(), + or <methodname><link linkend="function-gio--buffered-input-stream-new-sized">gio.buffered_input_stream_new_sized</link></methodname>() + to specify the buffer's size at construction. + </para> + <para> + To get the size of a buffer within a buffered input stream, use + <methodname><link linkend="method-giobufferedinputstream--get-buffer-size">get_buffer_size</link></methodname>(). + To change the size of a buffered input stream's buffer, use + <methodname><link linkend="method-giobufferedinputstream--set-buffer-size">set_buffer_size</link></methodname>(). + Note that the buffer's size cannot be reduced below the size of the data within the buffer. + </para> + </refsect1> + + <refsect1 id="constructor-giobufferedinputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.BufferedInputStream</methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>base_stream</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + for the given base_stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + from the given base_stream, with a buffer set to the default size (4 kilobytes). + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giobufferedinputstream--fill"> + <title>gio.BufferedInputStream.fill</title> + + <programlisting><methodsynopsis language="python"> + <methodname>fill</methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">count</parameter> :</term> + <listitem><simpara>the number of bytes that will be read from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the number of bytes read into stream's buffer, + up to count, or -1 on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>fill</methodname>() method tries to read count bytes + from the stream into the buffer. Will block during this read. + </para> + <para> + If count is zero, returns zero and does nothing. A value of count + larger than G_MAXSSIZE will cause a gio.ERROR_INVALID_ARGUMENT error. + </para> + <para> + On success, the number of bytes read into the buffer is returned. It + is not an error if this is not the same as the requested size, as it can + happen e.g. near the end of a file. Zero is returned on end of file + (or if count is zero), but never otherwise. + </para> + <para> + If count is -1 then the attempted read size is equal to the number + of bytes that are required to fill the buffer. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can + be cancelled by triggering the cancellable object from another thread. + If the operation was cancelled, the error gio.ERROR_CANCELLED will be + returned. If an operation was partially finished when the operation was + cancelled the partial result will be returned, without an error. + </para> + <para> + On error -1 is returned and error is set accordingly. + </para> + <para> + For the asynchronous, non-blocking, version of this function, see + <methodname><link linkend="method-giobufferedinputstream--fill-async">gio.BufferedInputStream.fill_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giobufferedinputstream--fill-async"> + <title>gio.BufferedInputStream.fill_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>fill_async</methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">count</parameter> :</term> + <listitem><simpara>the number of bytes that will be read from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>fill_async</methodname>() method reads data into stream's + buffer asynchronously, up to count size. io_priority can be used to + prioritize reads. + </para> + <para> + For the synchronous version of this function, see + <methodname><link linkend="method-giobufferedinputstream--fill">gio.BufferedInputStream.fill</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was + cancelled, the error gio.ERROR_CANCELLED will be set + </para> + <para> + If count is -1 then the attempted read size is equal to the number of bytes + that are required to fill the buffer. + </para> + </refsect2> + + <refsect2 id="method-giobufferedinputstream--fill-finish"> + <title>gio.BufferedInputStream.fill_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>fill_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the size of the read stream, or -1 on an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>fill_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giobufferedinputstream--fill-async">gio.BufferedInputStream.fill_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giobufferedinputstream--get-available"> + <title>gio.BufferedInputStream.get_available</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_available</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>size of the available stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_available</methodname>() method gets the size of + the available data within the stream. + </para> + </refsect2> + + <refsect2 id="method-giobufferedinputstream--get-buffer-size"> + <title>gio.BufferedInputStream.get_buffer_size</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_buffer_size</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the current buffer size. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_buffer_size</methodname>() method gets the size + of the input buffer. + </para> + </refsect2> + + <refsect2 id="method-giobufferedinputstream--read-byte"> + <title>gio.BufferedInputStream.read_byte</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_byte</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the byte read from the stream, or -1 on end of stream or error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_byte</methodname>() method tries to read a single + byte from the stream or the buffer. Will block during this read. + </para> + <para> + On success, the byte read from the stream is returned. On end of stream -1 + is returned but it's not an exceptional error and error is not set. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can + be cancelled by triggering the cancellable object from another thread. + If the operation was cancelled, the error gio.ERROR_CANCELLED will be + returned. If an operation was partially finished when the operation was + cancelled the partial result will be returned, without an error. + </para> + <para> + On error -1 is returned and error is set accordingly. + </para> + </refsect2> + + <refsect2 id="method-giobufferedinputstream--set-buffer-size"> + <title>gio.BufferedInputStream.set_buffer_size</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_buffer_size</methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">size</parameter> :</term> + <listitem><simpara>the new buffer size. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_buffer_size</methodname>() method sets the size + of the internal buffer of stream to size, or to the size of the contents + of the buffer. The buffer can never be resized smaller than its current contents. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--buffered-input-stream-new-sized"> + <title>gio.buffered_input_stream_new_sized</title> + + <programlisting><methodsynopsis language="python"> + <methodname>buffered_input_stream_new_sized</methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>size</parameter> :</term> + <listitem><simpara>the requested buffer size. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A new + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>buffered_input_stream_new_sized</methodname>() function creates + a new <link linkend="class-giobufferedinputstream"><classname>gio.BufferedInputStream</classname></link> + from the given base_stream, with a buffer set to size. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-bufferedoutputstream.xml b/docs/reference/pygio-bufferedoutputstream.xml new file mode 100644 index 0000000..6d7900f --- /dev/null +++ b/docs/reference/pygio-bufferedoutputstream.xml @@ -0,0 +1,275 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giobufferedoutputstream"> + <refnamediv> + <refname>gio.BufferedOutputStream</refname> + <refpurpose>Buffered Output Stream</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.BufferedOutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giofilteroutputstream">gio.FilterOutputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giobufferedoutputstream">gio.BufferedOutputStream</link></methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedoutputstream--get-auto-grow">get_auto_grow</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedoutputstream--get-buffer-size">get_buffer_size</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedoutputstream--set-auto-grow">set_auto_grow</link></methodname> + <methodparam><parameter role="keyword">auto_grow</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giobufferedoutputstream--set-buffer-size">set_buffer_size</link></methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--buffered-output-stream-new-sized">gio.buffered_output_stream_new_sized</link></methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> + +-- <link linkend="class-giofilteroutputstream">gio.FilterOutputStream</link> + +-- <link linkend="class-giobufferedoutputstream">gio.BufferedOutputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giobufferedoutputstream"> + <title>gio.BufferedOutputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"auto-grow"</entry> + <entry>Read - Write</entry> + <entry>Whether the buffer should automatically grow. Default value: <literal>False</literal>.</entry> + </row> + <row valign="top"> + <entry>"buffer-size"</entry> + <entry>Read - Write - Construct</entry> + <entry>The size of the backend buffer. Allowed values: >= 1. Default value: 4096.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giobufferedoutputstream"><classname>gio.BufferedOutputStream</classname></link> + implements <link linkend="class-giofilteroutputstream"><classname>gio.FilterOutputStream</classname></link> + and provides for buffered writes. + </para> + <para> + By default, + <link linkend="class-giobufferedoutputstream"><classname>gio.BufferedOutputStream</classname></link>'s + buffer size is set at 4 kilobytes. + </para> + <para> + To create a buffered output stream, use + <methodname><link linkend="constructor-giobufferedoutputstream">gio.BufferedOutputStream</link></methodname>(), + or <methodname><link linkend="function-gio--buffered-output-stream-new-sized">gio.buffered_output_stream_new_sized</link></methodname>() + to specify the buffer's size at construction. + </para> + <para> + To get the size of a buffer within a buffered output stream, use + <methodname><link linkend="method-giobufferedoutputstream--get-buffer-size">gio.BufferedOutputStream.get_buffer_size</link></methodname>(). + To change the size of a buffered output stream's buffer, use + <methodname><link linkend="method-giobufferedoutputstream--set-buffer-size">gio.BufferedOutputStream.set_buffer_size</link></methodname>(). + Note that the buffer's size cannot be reduced below the size of the data within the buffer. + </para> + </refsect1> + + <refsect1 id="constructor-giobufferedoutputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.BufferedOutputStream</methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>base_stream</parameter> :</term> + <listitem><simpara>a + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + for the given base_stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new buffered output stream for a base stream. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giobufferedoutputstream--get-auto-grow"> + <title>gio.BufferedOutputStream.get_auto_grow</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_auto_grow</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the stream's + buffer automatically grows, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_auto_grow</methodname>() method checks if the + buffer automatically grows as data is added. + </para> + </refsect2> + + <refsect2 id="method-giobufferedoutputstream--get-buffer-size"> + <title>gio.BufferedOutputStream.get_buffer_size</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_buffer_size</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the current buffer size. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_buffer_size</methodname>() method gets the size + of the buffer in the stream. + </para> + </refsect2> + + <refsect2 id="method-giobufferedoutputstream--set-auto-grow"> + <title>gio.BufferedOutputStream.set_auto_grow</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_auto_grow</methodname> + <methodparam><parameter role="keyword">auto_grow</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">auto_grow</parameter> :</term> + <listitem><simpara>a boolean. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_auto_grow</methodname>() method sets whether or not + the stream's buffer should automatically grow. If auto_grow is true, + then each write will just make the buffer larger, and you must manually + flush the buffer to actually write out the data to the underlying stream. + </para> + </refsect2> + + <refsect2 id="method-giobufferedoutputstream--set-buffer-size"> + <title>gio.BufferedOutputStream.set_buffer_size</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_buffer_size</methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">size</parameter> :</term> + <listitem><simpara>the new buffer size. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_buffer_size</methodname>() method sets the size of + the internal buffer to size. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--buffered-output-stream-new-sized"> + <title>gio.buffered_output_stream_new_sized</title> + + <programlisting><methodsynopsis language="python"> + <methodname>buffered_output_stream_new_sized</methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>size</parameter> :</term> + <listitem><simpara>the requested buffer size. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A new + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + with an internal buffer set to size.. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>buffered_output_stream_new_sized</methodname>() function creates + a new <link linkend="class-giobufferedoutputstream"><classname>gio.BufferedOutputStream</classname></link> + from the given base_stream, with a buffer set to size. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-cancellable.xml b/docs/reference/pygio-cancellable.xml new file mode 100644 index 0000000..c35388d --- /dev/null +++ b/docs/reference/pygio-cancellable.xml @@ -0,0 +1,290 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giocancellable"> + <refnamediv> + <refname>gio.Cancellable</refname> + <refpurpose>Thread-safe Operation Cancellation Stack.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Cancellable</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giocancellable">gio.Cancellable</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--cancel">cancel</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--get-fd">get_fd</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--is-cancelled">is_cancelled</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--pop-current">pop_current</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--push-current">push_current</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--reset">reset</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giocancellable--set-error-if-cancelled">set_error_if_cancelled</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--cancellable-get-current">gio.cancellable_get_current</link></methodname> + <methodparam></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giocancellable">gio.Cancellable</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + is a thread-safe operation cancellation stack used throughout GIO to allow for + cancellation of synchronous and asynchronous operations. + </para> + </refsect1> + + <refsect1 id="constructor-giocancellable"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.Cancellable</methodname> + <methodparam></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> object. + </para> + <para> + Applications that want to start one or more operations that should be cancellable should create a + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + and pass it to the operations. + </para> + <para> + One <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + can be used in multiple consecutive operations, but not in multiple concurrent operations. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giocancellable--cancel"> + <title>gio.Cancellable.cancel</title> + + <programlisting><methodsynopsis language="python"> + <methodname>cancel</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>cancel</methodname>() method will set cancellable to cancelled, + and will emit the "cancelled" signal. (However, see the warning about race conditions + in the documentation for that signal if you are planning to connect to it.) + </para> + <para> + This function is thread-safe. In other words, you can safely call it from a thread + other than the one running the operation that was passed the cancellable. + </para> + <para> + The convention within gio is that cancelling an asynchronous operation causes it + to complete asynchronously. That is, if you cancel the operation from the same thread + in which it is running, then the operation's GAsyncReadyCallback will not be invoked + until the application returns to the main loop. + </para> + </refsect2> + + <refsect2 id="method-giocancellable--get-fd"> + <title>gio.Cancellable.get_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_fd</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A valid file descriptor. -1 if the file descriptor + is not supported, or on errors.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_fd</methodname>() method gets the file descriptor + for a cancellable job. This can be used to implement cancellable operations + on Unix systems. The returned fd will turn readable when cancellable is cancelled. + </para> + </refsect2> + + <refsect2 id="method-giocancellable--is-cancelled"> + <title>gio.Cancellable.is_cancelled</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_cancelled</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if cancellable is cancelled, + <literal>False</literal> if called with <literal>None</literal> or if + item is not cancelled. </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_fd</methodname>() method gets the file descriptor + for a cancellable job. This can be used to implement cancellable operations + on Unix systems. The returned fd will turn readable when cancellable is cancelled. + </para> + </refsect2> + + <refsect2 id="method-giocancellable--pop-current"> + <title>gio.Cancellable.pop_current</title> + + <programlisting><methodsynopsis language="python"> + <methodname>pop_current</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>pop_current</methodname>() method pops cancellable off + the cancellable stack (verifying that cancellable is on the top of the stack). + </para> + </refsect2> + + <refsect2 id="method-giocancellable--push-current"> + <title>gio.Cancellable.push_current</title> + + <programlisting><methodsynopsis language="python"> + <methodname>push_current</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>push_current</methodname>() method pushes cancellable onto + the cancellable stack. The current cancllable can then be recieved using + <methodname><link linkend="function-gio--cancellable-get-current">gio.cancellable_get_current</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giocancellable--reset"> + <title>gio.Cancellable.reset</title> + + <programlisting><methodsynopsis language="python"> + <methodname>reset</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>reset</methodname>() method resets cancellable to its uncancelled state. + </para> + </refsect2> + + <refsect2 id="method-giocancellable--set-error-if-cancelled"> + <title>gio.Cancellable.set_error_if_cancelled</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_error_if_cancelled</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if cancellable was cancelled, + <literal>False</literal> if it was not.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_error_if_cancelled</methodname>() method, if the cancellable + is cancelled, sets the error to notify that the operation was cancelled. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--cancellable-get-current"> + <title>gio.cancellable_get_current</title> + + <programlisting><methodsynopsis language="python"> + <methodname>cancellable_get_current</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + from the top of the stack, or <literal>None</literal> if the stack is empty.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>cancellable_get_current</methodname>() function gets the top cancellable from the stack. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-classes.xml b/docs/reference/pygio-classes.xml new file mode 100644 index 0000000..17761f8 --- /dev/null +++ b/docs/reference/pygio-classes.xml @@ -0,0 +1,47 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<chapter id="gio-class-reference" + xmlns:xi="http://www.w3.org/2001/XInclude"> + +<title>PyGio Class Reference</title> + +<!-- GIO CLASSES --> +<xi:include href="pygio-appinfo.xml"/> +<xi:include href="pygio-applaunchcontext.xml"/> +<xi:include href="pygio-asyncresult.xml"/> +<xi:include href="pygio-bufferedinputstream.xml"/> +<xi:include href="pygio-bufferedoutputstream.xml"/> +<xi:include href="pygio-cancellable.xml"/> +<xi:include href="pygio-datainputstream.xml"/> +<xi:include href="pygio-dataoutputstream.xml"/> +<xi:include href="pygio-drive.xml"/> +<xi:include href="pygio-emblem.xml"/> +<xi:include href="pygio-emblemedicon.xml"/> +<xi:include href="pygio-file.xml"/> +<xi:include href="pygio-fileattributeinfo.xml"/> +<xi:include href="pygio-fileenumerator.xml"/> +<xi:include href="pygio-fileicon.xml"/> +<xi:include href="pygio-fileinfo.xml"/> +<xi:include href="pygio-fileinputstream.xml"/> +<xi:include href="pygio-filemonitor.xml"/> +<xi:include href="pygio-fileoutputstream.xml"/> +<xi:include href="pygio-filterinputstream.xml"/> +<xi:include href="pygio-filteroutputstream.xml"/> +<xi:include href="pygio-icon.xml"/> +<xi:include href="pygio-inputstream.xml"/> +<xi:include href="pygio-loadableicon.xml"/> +<xi:include href="pygio-memoryinputstream.xml"/> +<xi:include href="pygio-memoryoutputstream.xml"/> +<xi:include href="pygio-mount.xml"/> +<xi:include href="pygio-mountoperation.xml"/> +<xi:include href="pygio-outputstream.xml"/> +<xi:include href="pygio-seekable.xml"/> +<xi:include href="pygio-simpleasyncresult.xml"/> +<xi:include href="pygio-themedicon.xml"/> +<xi:include href="pygio-volume.xml"/> +<xi:include href="pygio-volumemonitor.xml"/> +<xi:include href="pygio-functions.xml"/> +<xi:include href="pygio-constants.xml"/> + +</chapter> diff --git a/docs/reference/pygio-constants.xml b/docs/reference/pygio-constants.xml new file mode 100644 index 0000000..343927e --- /dev/null +++ b/docs/reference/pygio-constants.xml @@ -0,0 +1,1540 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="gio-constants"> + <refnamediv> + <refname>gio Constants</refname> + <refpurpose>the built-in constants of the gio module</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<programlisting> +<xref linkend="gio-app-info-constants" endterm="gio-app-info-constants-title"></xref> +<xref linkend="gio-ask-password-flags-constants" endterm="gio-ask-password-flags-constants-title"></xref> +<xref linkend="gio-data-stream-byte-order-constants" endterm="gio-data-stream-byte-order-constants-title"></xref> +<xref linkend="gio-data-stream-newline-type-constants" endterm="gio-data-stream-newline-type-constants-title"></xref> +<xref linkend="gio-emblem-origin-constants" endterm="gio-emblem-origin-constants-title"></xref> +<xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref> +<xref linkend="gio-file-attribute-constants" endterm="gio-file-attribute-constants-title"></xref> +<xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> +<xref linkend="gio-file-attribute-flags-constants" endterm="gio-file-attribute-flags-constants-title"></xref> +<xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> +<xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref> +<xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref> +<xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> +<xref linkend="gio-file-type-constants" endterm="gio-file-type-constants-title"></xref> +<xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref> +<xref linkend="gio-mount-operation-result-constants" endterm="gio-mount-operation-result-constants-title"></xref> +<xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref> +<xref linkend="gio-password-save-constants" endterm="gio-password-save-constants-title"></xref> +</programlisting> + + </refsect1> + + <refsect1 id="gio-constants-description"> + <title>Description</title> + + <refsect2 id="gio-ask-password-flags-constants"> + <title id="gio-ask-password-flags-constants-title">Gio Ask Password Flags Constants</title> + + <para> + Flags that are used to request specific information from the user, or to + notify the user of their choices in an authentication situation. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.ASK_PASSWORD_ANONYMOUS_SUPPORTED</literal></term> + <listitem> + <simpara>operation supports anonymous users.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ASK_PASSWORD_NEED_DOMAIN</literal></term> + <listitem> + <simpara>operation requires a domain.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ASK_PASSWORD_NEED_PASSWORD</literal></term> + <listitem> + <simpara>operation requires a password.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ASK_PASSWORD_NEED_USERNAME</literal></term> + <listitem> + <simpara>operation requires a username.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ASK_PASSWORD_SAVING_SUPPORTED</literal></term> + <listitem> + <simpara>operation supports saving settings.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-app-info-constants"> + <title id="gio-app-info-constants-title">Gio AppInfo Create Flags Constants</title> + + <para> + Flags used when creating a <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.APP_INFO_CREATE_NONE</literal></term> + <listitem> + <simpara>No flags.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.APP_INFO_CREATE_NEEDS_TERMINAL</literal></term> + <listitem> + <simpara>Application opens in a terminal window. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.APP_INFO_CREATE_SUPPORTS_URIS</literal></term> + <listitem> + <simpara>Application supports URI arguments. </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-data-stream-byte-order-constants"> + <title id="gio-data-stream-byte-order-constants-title">Gio Data Stream Byte Order Constants</title> + + <para> + Used to ensure proper endianness of streaming data sources across various machine architectures. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.DATA_STREAM_BYTE_ORDER_BIG_ENDIAN</literal></term> + <listitem> + <simpara>Selects Big Endian byte order.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.DATA_STREAM_BYTE_ORDER_HOST_ENDIAN</literal></term> + <listitem> + <simpara>Selects endianness based on host machine's architecture.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.DATA_STREAM_BYTE_ORDER_LITTLE_ENDIAN</literal></term> + <listitem> + <simpara>Selects Little Endian byte order.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-data-stream-newline-type-constants"> + <title id="gio-data-stream-newline-type-constants-title">Gio Data Stream Newline Type Constants</title> + + <para> + Used when checking for or setting the line endings for a given file. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.DATA_STREAM_NEWLINE_TYPE_LF</literal></term> + <listitem> + <simpara>Selects "LF" line endings, common on most modern UNIX platforms.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.DATA_STREAM_NEWLINE_TYPE_CR</literal></term> + <listitem> + <simpara>Selects "CR" line endings.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.DATA_STREAM_NEWLINE_TYPE_CR_LF</literal></term> + <listitem> + <simpara>Selects "CR, LF" line ending, common on Microsoft Windows.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.DATA_STREAM_NEWLINE_TYPE_ANY</literal></term> + <listitem> + <simpara>Automatically try to handle any line ending type.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-emblem-origin-constants"> + <title id="gio-emblem-origin-constants-title">Gio Emblem Origin Constants</title> + + <para> + GEmblemOrigin is used to add information about the origin of the emblem to GEmblem. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.EMBLEM_ORIGIN_DEVICE</literal></term> + <listitem> + <simpara>Embleme adds device-specific information.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.EMBLEM_ORIGIN_LIVEMETADATA</literal></term> + <listitem> + <simpara>Emblem depicts live metadata, such as "readonly".</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.EMBLEM_ORIGIN_TAG</literal></term> + <listitem> + <simpara>Emblem comes from a user-defined tag, e.g. set by nautilus (in the future).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.EMBLEM_ORIGIN_UNKNOWN</literal></term> + <listitem> + <simpara>Emblem of unknown origin.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-error-constants"> + <title id="gio-error-constants-title">Gio Error Constants</title> + + <para> + GIOError Error codes returned by GIO functions. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.ERROR_ALREADY_MOUNTED</literal></term> + <listitem> + <simpara>File is already mounted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_BUSY</literal></term> + <listitem> + <simpara>File is busy.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_CANCELLED</literal></term> + <listitem> + <simpara>Operation was cancelled. See + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_CANT_CREATE_BACKUP</literal></term> + <listitem> + <simpara>Backup couldn't be created.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_CLOSED</literal></term> + <listitem> + <simpara>File was closed.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_EXISTS</literal></term> + <listitem> + <simpara>File already exists error.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_FAILED</literal></term> + <listitem> + <simpara>Generic error condition for when any operation fails.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_FAILED_HANDLED</literal></term> + <listitem> + <simpara>Operation failed and a helper program has already interacted with + the user. Do not display any error dialog. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_FILENAME_TOO_LONG</literal></term> + <listitem> + <simpara>Filename is too many characters.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_HOST_NOT_FOUND</literal></term> + <listitem> + <simpara>Host couldn't be found (remote operations).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_INVALID_ARGUMENT</literal></term> + <listitem> + <simpara>Invalid argument.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_INVALID_FILENAME</literal></term> + <listitem> + <simpara>Filename is invalid or contains invalid characters.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_IS_DIRECTORY</literal></term> + <listitem> + <simpara>File is a directory error.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_DIRECTORY</literal></term> + <listitem> + <simpara>File is not a directory.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_EMPTY</literal></term> + <listitem> + <simpara>File is a directory that isn't empty.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_FOUND</literal></term> + <listitem> + <simpara>File not found error.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_MOUNTABLE_FILE</literal></term> + <listitem> + <simpara>File cannot be mounted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_MOUNTED</literal></term> + <listitem> + <simpara>File isn't mounted. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_REGULAR_FILE</literal></term> + <listitem> + <simpara>File is not a regular file.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_SUPPORTED</literal></term> + <listitem> + <simpara>Operation not supported for the current backend.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NOT_SYMBOLIC_LINK</literal></term> + <listitem> + <simpara>File is not a symbolic link.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_NO_SPACE</literal></term> + <listitem> + <simpara>No space left on drive. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_PENDING</literal></term> + <listitem> + <simpara>Operations are still pending.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_PERMISSION_DENIED</literal></term> + <listitem> + <simpara>Permission denied.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_READ_ONLY</literal></term> + <listitem> + <simpara>File is read only. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_TIMED_OUT</literal></term> + <listitem> + <simpara>Operation timed out. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_TOO_MANY_LINKS</literal></term> + <listitem> + <simpara>File contains too many symbolic links. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_TOO_MANY_OPEN_FILES</literal></term> + <listitem> + <simpara>The current process has too many files open and can't open any + more. Duplicate descriptors do count toward this limit. Since 2.20</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_WOULD_BLOCK</literal></term> + <listitem> + <simpara>Operation would block.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_WOULD_MERGE</literal></term> + <listitem> + <simpara>Operation would merge files.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_WOULD_RECURSE</literal></term> + <listitem> + <simpara>Operation would be recursive.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.ERROR_WRONG_ETAG</literal></term> + <listitem> + <simpara>File's Entity Tag was incorrect. </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-attribute-constants"> + <title id="gio-file-attribute-constants-title">Gio File Attribute Constants</title> + + <para> + The file attributes. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_TYPE</literal></term> + <listitem> + <simpara> + "standard::type" A key in the "standard" namespace for storing file types. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. The value for this key should contain a + <xref linkend="gio-file-type-constants" endterm="gio-file-type-constants-title"></xref> + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</literal></term> + <listitem> + <simpara> + "standard::is-hidden" A key in the "standard" namespace for checking if a file is hidden. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_BACKUP</literal></term> + <listitem> + <simpara> + "standard::is-backup" A key in the "standard" namespace for checking if a file is a backup file. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</literal></term> + <listitem> + <simpara> + "standard::is-symlink" A key in the "standard" namespace for checking if the file is a symlink. + Typically the actual type is something else, if we followed the symlink to get the type. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</literal></term> + <listitem> + <simpara> + "standard::is-virtual" A key in the "standard" namespace for checking if a file is virtual. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_NAME</literal></term> + <listitem> + <simpara> + "standard::name" A key in the "standard" namespace for getting the name of the file. + The name is the on-disk filename which may not be in any known encoding, + and can thus not be generally displayed as is. Use + gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user + interface. Corresponding GFileAttributeType is gio.FILE_ATTRIBUTE_TYPE_BYTE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</literal></term> + <listitem> + <simpara> + "standard::display-name" A key in the "standard" namespace for getting the display + name of the file. A display name is guaranteed to be in UTF8 and can thus be displayed + in the UI. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME</literal></term> + <listitem> + <simpara> + "standard::edit-name" A key in the "standard" namespace for edit name of the file. + An edit name is similar to the display name, but it is meant to be used when you want + to rename the file in the UI. The display name might contain information you don't + want in the new filename (such as "(invalid unicode)" if the filename was in an + invalid encoding). Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_COPY_NAME</literal></term> + <listitem> + <simpara> + "standard::copy-name" A key in the "standard" namespace for getting the copy + name of the file. The copy name is an optional version of the name. If available + it's always in UTF8, and corresponds directly to the original filename (only transcoded + to UTF8). This is useful if you want to copy the file to another filesystem that might + have a different encoding. If the filename is not a valid string in the encoding selected + for the filesystem it is in then the copy name will not be set. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_ICON</literal></term> + <listitem> + <simpara> + "standard::icon" A key in the "standard" namespace for getting the icon for the file. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link>. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</literal></term> + <listitem> + <simpara> + "standard::content-type" A key in the "standard" namespace for getting the content type of the file. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. The value for this key should contain a valid content type. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</literal></term> + <listitem> + <simpara> + "standard::fast-content-type" A key in the "standard" namespace for getting the fast + content type. The fast content type isn't as reliable as the regular one, as it + only uses the filename to guess it, but it is faster to calculate than the regular + content type. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_SIZE</literal></term> + <listitem> + <simpara> + "standard::size" A key in the "standard" namespace for getting the file's size (in bytes). Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT64. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</literal></term> + <listitem> + <simpara> + "standard::symlink-target" A key in the "standard" namespace for getting the target URI + for the file, in the case of gio.FILE_TYPE_SHORTCUT or gio.FILE_TYPE_MOUNTABLE files. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_SORT_ORDER</literal></term> + <listitem> + <simpara> + "standard::sort-order" A key in the "standard" namespace for setting the sort order of a file. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_INT32. An example use would be in file managers, which would use this + key to set the order files are displayed. Files with smaller sort order should be sorted first, + and files without sort order as if sort order was zero. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ETAG_VALUE</literal></term> + <listitem> + <simpara> + "etag::value" A key in the "etag" namespace for getting the value of the file's entity tag. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ID_FILE</literal></term> + <listitem> + <simpara> + "id::file" A key in the "id" namespace for getting a file identifier. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. An example use would be during listing files, + to avoid recursive directory scanning. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ID_FILESYSTEM</literal></term> + <listitem> + <simpara> + "id::filesystem" A key in the "id" namespace for getting the file system identifier. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. An example use would be during drag and + drop to see if the source and target are on the same filesystem (default to move) or not (default to copy). + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_READ</literal></term> + <listitem> + <simpara> + "access::can-read" A key in the "access" namespace for getting read privileges. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal> + if the user is able to read the file. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_WRITE</literal></term> + <listitem> + <simpara> + "access::can-write" A key in the "access" namespace for getting write privileges.Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal> + if the user is able to write to the file. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</literal></term> + <listitem> + <simpara> + "access::can-execute" A key in the "access" namespace for getting execution privileges. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal> + if the user is able to execute the file. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_DELETE</literal></term> + <listitem> + <simpara> + "access::can-delete" A key in the "access" namespace for checking deletion privileges. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal> + if the user is able to delete the file. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_TRASH</literal></term> + <listitem> + <simpara> + "access::can-trash" A key in the "access" namespace for checking trashing privileges. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal> + if the user is able to move the file to the trash. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_ACCESS_CAN_RENAME</literal></term> + <listitem> + <simpara> + "access::can-rename" A key in the "access" namespace for checking renaming privileges. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. This attribute will be <literal>True</literal> + if the user is able to rename the file. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</literal></term> + <listitem> + <simpara> + "mountable::can-mount" A key in the "mountable" namespace for checking if + a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</literal></term> + <listitem> + <simpara> + "mountable::can-unmount" A key in the "mountable" namespace for checking if a file + (of type G_FILE_TYPE_MOUNTABLE) is unmountable. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</literal></term> + <listitem> + <simpara> + "mountable::can-eject" A key in the "mountable" namespace for checking if a file + (of type G_FILE_TYPE_MOUNTABLE) can be ejected. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</literal></term> + <listitem> + <simpara> + "mountable::unix-device" A key in the "mountable" namespace for getting the unix device. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</literal></term> + <listitem> + <simpara> + "mountable::hal-udi" A key in the "mountable" namespace for getting the + HAL UDI for the mountable file. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_MODIFIED</literal></term> + <listitem> + <simpara> + "time::modified" A key in the "time" namespace for getting the time the file was last modified. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was modified. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_MODIFIED_USEC</literal></term> + <listitem> + <simpara> + "time::modified-usec" A key in the "time" namespace for getting the miliseconds + of the time the file was last modified. This should be used in conjunction + with G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_ACCESS</literal></term> + <listitem> + <simpara> + "time::access" A key in the "time" namespace for getting the time the file was last accessed. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was last accessed. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_ACCESS_USEC</literal></term> + <listitem> + <simpara> + "time::access-usec" A key in the "time" namespace for getting the microseconds of + the time the file was last accessed. This should be used in conjunction + with G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_CHANGED</literal></term> + <listitem> + <simpara> + "time::changed" A key in the "time" namespace for getting the time the + file was last changed. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was last changed. + This corresponds to the traditional UNIX ctime. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_CHANGED_USEC</literal></term> + <listitem> + <simpara> + "time::changed-usec" A key in the "time" namespace for getting the microseconds + of the time the file was last changed. This should be used in conjunction + with G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_CREATED</literal></term> + <listitem> + <simpara> + "time::created" A key in the "time" namespace for getting the time the file was created. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT64, and contains the UNIX time since the file was created. + This corresponds to the NTFS ctime. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TIME_CREATED_USEC</literal></term> + <listitem> + <simpara> + "time::created-usec" A key in the "time" namespace for getting the microseconds of the time the + file was created. This should be used in conjunction with G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_DEVICE</literal></term> + <listitem> + <simpara> + "unix::device" A key in the "unix" namespace for getting the device id of the device the file + is located on (see stat() documentation). This attribute is only available + for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_INODE</literal></term> + <listitem> + <simpara> + "unix::inode" A key in the "unix" namespace for getting the inode of the file. This attribute is only + available for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_UINT64. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_MODE</literal></term> + <listitem> + <simpara> + "unix::mode" A key in the "unix" namespace for getting the mode of the file (e.g. + whether the file is a regular file, symlink, etc). See lstat() documentation. + This attribute is only available for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_NLINK</literal></term> + <listitem> + <simpara> + "unix::nlink" A key in the "unix" namespace for getting the number of hard links + for a file. See lstat() documentation. This attribute is only available for UNIX + file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_UID</literal></term> + <listitem> + <simpara> + "unix::uid" A key in the "unix" namespace for getting the user ID for the file. This attribute + is only available for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_GID</literal></term> + <listitem> + <simpara> + "unix::gid" A key in the "unix" namespace for getting the group ID for the file. + This attribute is only available for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_RDEV</literal></term> + <listitem> + <simpara> + "unix::rdev" A key in the "unix" namespace for getting the device ID for the file + (if it is a special file). See lstat() documentation. This attribute is only available + for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</literal></term> + <listitem> + <simpara> + "unix::block-size" A key in the "unix" namespace for getting the block size for + the file system. This attribute is only available for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is gio.FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_BLOCKS</literal></term> + <listitem> + <simpara> + "unix::blocks" A key in the "unix" namespace for getting the number of blocks allocated + for the file. This attribute is only available for UNIX file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_UINT64. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</literal></term> + <listitem> + <simpara> + "unix::is-mountpoint" A key in the "unix" namespace for checking if the file represents + a UNIX mount point. This attribute is <literal>True</literal> if the file is a UNIX mount point. + This attribute is only available for UNIX file systems. Corresponding + GFileAttributeType + is gio.FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_DOS_IS_ARCHIVE</literal></term> + <listitem> + <simpara> + "dos::is-archive" A key in the "dos" namespace for checking if the file's archive + flag is set. This attribute is <literal>True</literal> if the archive flag is set. + This attribute is only available for DOS file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_DOS_IS_SYSTEM</literal></term> + <listitem> + <simpara> + "dos::is-system" A key in the "dos" namespace for checking if the file's backup + flag is set. This attribute is <literal>True</literal> if the backup flag is set. + This attribute is only available for DOS file systems. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> is + G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_OWNER_USER</literal></term> + <listitem> + <simpara> + "owner::user" A key in the "owner" namespace for getting the user name + of the file's owner. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_OWNER_USER_REAL</literal></term> + <listitem> + <simpara> + "owner::user-real" A key in the "owner" namespace for getting the real name + of the user that owns the file. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> is + G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_OWNER_GROUP</literal></term> + <listitem> + <simpara> + "owner::group" A key in the "owner" namespace for getting the file owner's + group. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_THUMBNAIL_PATH</literal></term> + <listitem> + <simpara> + "thumbnail::path" A key in the "thumbnail" namespace for getting the path + to the thumbnail image. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_THUMBNAILING_FAILED</literal></term> + <listitem> + <simpara> + "thumbnail::failed" A key in the "thumbnail" namespace for checking if thumbnailing failed. This attribute + is <literal>True</literal> if thumbnailing failed. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> is + G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_PREVIEW_ICON</literal></term> + <listitem> + <simpara> + "preview::icon" A key in the "preview" namespace for getting a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + that can be used to get preview of the file. For example, it + may be a low resolution thumbnail without metadata. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> is + G_FILE_ATTRIBUTE_TYPE_OBJECT. The value for this key should contain a GIcon. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_FILESYSTEM_SIZE</literal></term> + <listitem> + <simpara> + "filesystem::size" A key in the "filesystem" namespace for getting the total + size (in bytes) of the file system, used in + <methodname><link linkend="method-giofile--query-filesystem-info">query_filesystem_info</link></methodname>(). + Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_UINT64. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_FILESYSTEM_FREE</literal></term> + <listitem> + <simpara> + "filesystem::free" A key in the "filesystem" namespace for getting the number of bytes of free space left + on the file system. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_UINT64. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_FILESYSTEM_TYPE</literal></term> + <listitem> + <simpara> + "filesystem::type" A key in the "filesystem" namespace for getting the file system's type. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_FILESYSTEM_READONLY</literal></term> + <listitem> + <simpara> + "filesystem::readonly" A key in the "filesystem" namespace for checking if the + file system is read only. Is set to <literal>True</literal> if the file system + is read only. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_GVFS_BACKEND</literal></term> + <listitem> + <simpara> + "gvfs::backend" A key in the "gvfs" namespace that gets the name of the current GVFS backend in use. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_SELINUX_CONTEXT</literal></term> + <listitem> + <simpara> + "selinux::context" A key in the "selinux" namespace for getting the file's SELinux context. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + Note that this attribute is only available if GLib has been built with SELinux support. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TRASH_ITEM_COUNT</literal></term> + <listitem> + <simpara> + "trash::item-count" A key in the "trash" namespace. When requested against "trash:///" returns the number + of (toplevel) items in the trash folder. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_UINT32. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW</literal></term> + <listitem> + <simpara> + "filesystem::use-preview" A key in the "filesystem" namespace for hinting a file manager + application whether it should preview (e.g. thumbnail) files on the file system. + The value for this key contain a GFilesystemPreviewType. + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_STANDARD_DESCRIPTION</literal></term> + <listitem> + <simpara> + "standard::description" A key in the "standard" namespace for getting the description + of the file. The description is a utf8 string that describes the file, generally containing + the filename, but can also contain furter information. Example descriptions could be + "filename (on hostname)" for a remote file or "filename (in trash)" for a + file in the trash. This is useful for instance as the window title when + displaying a directory or for a bookmarks menu. Corresponding + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + is G_FILE_ATTRIBUTE_TYPE_STRING. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-attribute-type-constants"> + <title id="gio-file-attribute-type-constants-title">Gio File Attribute Type Constants</title> + + <para> + The data types for file attributes. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_BOOLEAN</literal></term> + <listitem> + <simpara>a boolean value.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_BYTE_STRING</literal></term> + <listitem> + <simpara>a zero terminated string of non-zero bytes.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_INT32</literal></term> + <listitem> + <simpara>a signed 4-byte/32-bit integer.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_INT64</literal></term> + <listitem> + <simpara>a signed 8-byte/64-bit integer.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_INVALID</literal></term> + <listitem> + <simpara>indicates an invalid or uninitalized type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_OBJECT</literal></term> + <listitem> + <simpara>a <link linkend="class-gobject">gobject.GObject</link>.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_STRING</literal></term> + <listitem> + <simpara>a null terminated UTF8 string.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_UINT32</literal></term> + <listitem> + <simpara>an unsigned 4-byte/32-bit integer.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_TYPE_UINT64</literal></term> + <listitem> + <simpara>an unsigned 8-byte/64-bit integer.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-attribute-flags-constants"> + <title id="gio-file-attribute-flags-constants-title">Gio File Attribute Flags Constants</title> + + <para> + Flags specifying the behaviour of an attribute. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_INFO_NONE</literal></term> + <listitem> + <simpara>no flags set.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_INFO_COPY_WITH_FILE</literal></term> + <listitem> + <simpara>copy the attribute values when the file is copied.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_ATTRIBUTE_INFO_COPY_WHEN_MOVED</literal></term> + <listitem> + <simpara>copy the attribute values when the file is moved.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-create-flags-constants"> + <title id="gio-file-create-flags-constants-title">Gio File Create Flags Constants</title> + + <para> + Flags used when an operation may create a file. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_CREATE_NONE</literal></term> + <listitem> + <simpara>No flags set.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_CREATE_PRIVATE</literal></term> + <listitem> + <simpara>Create a file that can only be accessed by the current user.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_CREATE_REPLACE_DESTINATION</literal></term> + <listitem> + <simpara> + Replace the destination as if it didn't exist before. Don't try + to keep any old permissions, replace instead of following links. This is + generally useful if you're doing a "copy over" rather than a "save new version of" + replace operation. You can think of it as "unlink destination" before writing + to it, although the implementation may not be exactly like that. + </simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-copy-flags-constants"> + <title id="gio-file-copy-flags-constants-title">Gio File Copy Flags Constants</title> + + <para> + Flags used when copying or moving files. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_COPY_NONE</literal></term> + <listitem> + <simpara>No flags set.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_COPY_OVERWRITE</literal></term> + <listitem> + <simpara>Overwrite any existing files.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_COPY_BACKUP</literal></term> + <listitem> + <simpara>Make a backup of any existing files.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_COPY_NOFOLLOW_SYMLINKS</literal></term> + <listitem> + <simpara>Don't follow symlinks.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_COPY_ALL_METADATA</literal></term> + <listitem> + <simpara>Copy all file metadata instead of just default set used for copy + (see <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_COPY_NO_FALLBACK_FOR_MOVE</literal></term> + <listitem> + <simpara>Don't use copy and delete fallback if native move not supported.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_COPY_TARGET_DEFAULT_PERMS</literal></term> + <listitem> + <simpara>Leaves target file with default perms, instead of setting the source file perms.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-monitor-flags-constants"> + <title id="gio-file-monitor-flags-constants-title">Gio File Monitor Flags Constants</title> + + <para> + Flags used to set what a + <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link> + will watch for. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_MONITOR_NONE</literal></term> + <listitem> + <simpara>No flags set.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_MONITOR_WATCH_MOUNTS</literal></term> + <listitem> + <simpara>Watch for mount events.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-query-info-flags-constants"> + <title id="gio-file-query-info-flags-constants-title">Gio File Query Info Flags Constants</title> + + <para> + Flags used when querying a + <link linkend="class-giofile"><classname>gio.FileInfo</classname></link>. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_QUERY_INFO_NONE</literal></term> + <listitem> + <simpara>No flags set.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_QUERY_INFO_NOFOLLOW_SYMLINKS</literal></term> + <listitem> + <simpara>Don't follow symlinks.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-file-type-constants"> + <title id="gio-file-type-constants-title">Gio File Type Constants</title> + + <para> + Indicates the file's on-disk type. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.FILE_TYPE_DIRECTORY</literal></term> + <listitem> + <simpara>File handle represents a directory.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_TYPE_MOUNTABLE</literal></term> + <listitem> + <simpara>File is a mountable location.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_TYPE_REGULAR</literal></term> + <listitem> + <simpara>File handle represents a regular file.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_TYPE_SHORTCUT</literal></term> + <listitem> + <simpara>File is a shortcut (Windows systems).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_TYPE_SPECIAL</literal></term> + <listitem> + <simpara>File is a "special" file, such as a socket, fifo, block device, or character device.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_TYPE_SYMBOLIC_LINK</literal></term> + <listitem> + <simpara>File handle represents a symbolic link (Unix systems).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.FILE_TYPE_UNKNOWN</literal></term> + <listitem> + <simpara>File's type is unknown.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-mount-mount-flags-constants"> + <title id="gio-mount-mount-flags-constants-title">Gio Mount Mount Flags Constants</title> + + <para> + Flags used when mounting a mount. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.MOUNT_MOUNT_NONE</literal></term> + <listitem> + <simpara>No flags set.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-mount-unmount-flags-constants"> + <title id="gio-mount-unmount-flags-constants-title">Gio Mount Unmount Flags Constants</title> + + <para> + Flags used when unmounting a mount. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.MOUNT_UNMOUNT_NONE</literal></term> + <listitem> + <simpara>No flags set.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.MOUNT_UNMOUNT_FORCE</literal></term> + <listitem> + <simpara>Unmount even if there are outstanding file operations on the mount.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-mount-operation-result-constants"> + <title id="gio-mount-operation-result-constants-title">Gio Mount Operation Result Constants</title> + + <para> + returned as a result when a request for information is send by the mounting operation. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.MOUNT_OPERATION_HANDLED</literal></term> + <listitem> + <simpara>The request was fulfilled and the user specified data is now available.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.MOUNT_OPERATION_ABORTED</literal></term> + <listitem> + <simpara>The user requested the mount operation to be aborted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.MOUNT_OPERATION_UNHANDLED</literal></term> + <listitem> + <simpara>The request was unhandled (i.e. not implemented).</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="gio-password-save-constants"> + <title id="gio-password-save-constants-title">Gio Password Save Constants</title> + + <para> + is used to indicate the lifespan of a saved password. + </para> + <para> + Gvfs stores passwords in the Gnome keyring when this flag allows it to, + and later retrieves it again from there. + </para> + + <variablelist> + <varlistentry> + <term><literal>gio.PASSWORD_SAVE_FOR_SESSION</literal></term> + <listitem> + <simpara>save a password for the session.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.PASSWORD_SAVE_NEVER</literal></term> + <listitem> + <simpara>never save a password.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gio.PASSWORD_SAVE_PERMANENTLY</literal></term> + <listitem> + <simpara>save a password permanently.</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + </refsect1> + +</refentry> diff --git a/docs/reference/pygio-datainputstream.xml b/docs/reference/pygio-datainputstream.xml new file mode 100644 index 0000000..403bb3e --- /dev/null +++ b/docs/reference/pygio-datainputstream.xml @@ -0,0 +1,799 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giodatainputstream"> + <refnamediv> + <refname>gio.DataInputStream</refname> + <refpurpose>Data Input Stream</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.DataInputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giobufferedinputstream">gio.BufferedInputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giodatainputstream">gio.DataInputStream</link></methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--get-byte-order">get_byte_order</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--get-newline-type">get_newline_type</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-byte">read_byte</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-int16">read_int16</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-int32">read_int32</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-int64">read_int64</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-line">read_line</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-line-async">read_line_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-line-finish">read_line_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-uint16">read_uint16</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-uint32">read_uint32</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-uint64">read_uint64</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-until">read_until</link></methodname> + <methodparam><parameter role="keyword">stop_chars</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-until-async">read_until_async</link></methodname> + <methodparam><parameter role="keyword">stop_chars</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--read-until-finish">read_until_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--set-byte-order">set_byte_order</link></methodname> + <methodparam><parameter role="keyword">order</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodatainputstream--set-newline-type">set_newline_type</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> + +-- <link linkend="class-giofilterinputstream">gio.FilterInputStream</link> + +-- <link linkend="class-giobufferedinputstream">gio.BufferedInputStream</link> + +-- <link linkend="class-giodatainputstream">gio.DataInputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giodatainputstream"> + <title>gio.DataInputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"byte-order"</entry> + <entry>Read - Write</entry> + <entry>The byte order. Default value: gio.DATA_STREAM_BYTE_ORDER_BIG_ENDIAN.</entry> + </row> + <row valign="top"> + <entry>"newline-type"</entry> + <entry>Read - Write</entry> + <entry>The accepted types of line ending. Default value: gio.DATA_STREAM_NEWLINE_TYPE_LF.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giodatainputstream"><classname>gio.DataInputStream</classname></link> + implements <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + and includes functions for reading structured data directly from a binary input stream. + </para> + </refsect1> + + <refsect1 id="constructor-giodatainputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.DataInputStream</methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>base_stream</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giodatainputstream"><classname>gio.DataInputStream</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giodatainputstream"><classname>gio.DataInputStream</classname></link> + from the given base_stream. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giodatainputstream--get-byte-order"> + <title>gio.DataInputStream.get_byte_order</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_byte_order</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the stream's current + <xref linkend="gio-data-stream-byte-order-constants" endterm="gio-data-stream-byte-order-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_byte_order</methodname>() method gets the byte + order for the data input stream. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--get-newline-type"> + <title>gio.DataInputStream.get_newline_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_newline_type</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><xref linkend="gio-data-stream-newline-type-constants" endterm="gio-data-stream-newline-type-constants-title"></xref> + for the given stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_newline_type</methodname>() method gets the current + newline type for the stream. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-byte"> + <title>gio.DataInputStream.read_byte</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_byte</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an unsigned 8-bit/1-byte value read from the + stream or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_byte</methodname>() method reads an unsigned 8-bit/1-byte value from stream. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-int16"> + <title>gio.DataInputStream.read_int16</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_int16</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a signed 16-bit/2-byte value read from stream or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_int16</methodname>() method reads a 16-bit/2-byte value from stream. + </para> + <para> + In order to get the correct byte order for this read operation, see + <methodname><link linkend="method-giodatainputstream--get-byte_order">gio.DataInputStream.get_byte_order</link></methodname>() + and + <methodname><link linkend="method-giodatainputstream--set-byte_order">gio.DataInputStream.set_byte_order</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-int32"> + <title>gio.DataInputStream.read_int32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_int32</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a signed 32-bit/4-byte value read from the stream + or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_int32</methodname>() method reads a signed 32-bit/4-byte value from stream. + </para> + <para> + In order to get the correct byte order for this read operation, see + <methodname><link linkend="method-giodatainputstream--get-byte_order">gio.DataInputStream.get_byte_order</link></methodname>() + and + <methodname><link linkend="method-giodatainputstream--set-byte_order">gio.DataInputStream.set_byte_order</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-int64"> + <title>gio.DataInputStream.read_int64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_int64</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a signed 64-bit/8-byte value read from the stream + or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_int64</methodname>() method reads a signed 64-bit/8-byte value from stream. + </para> + <para> + In order to get the correct byte order for this read operation, see + <methodname><link linkend="method-giodatainputstream--get-byte_order">gio.DataInputStream.get_byte_order</link></methodname>() + and + <methodname><link linkend="method-giodatainputstream--set-byte_order">gio.DataInputStream.set_byte_order</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-line"> + <title>gio.DataInputStream.read_line</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_line</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string with the line that was read in (without the newlines). + Set length to a gsize to get the length of the read line. On an error, it will return + <literal>None</literal> and error will be set. If there's no content to read, it + will still return <literal>None</literal>, but error won't be set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_line</methodname>() reads a line from the data input stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can + be cancelled by triggering the cancellable object from another thread. + If the operation was cancelled, the error gio.ERROR_CANCELLED will be + returned. If an operation was partially finished when the operation was + cancelled the partial result will be returned, without an error. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-line-async"> + <title>gio.DataInputStream.read_line_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_line_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_line_async</methodname>() method is the asynchronous version of + <methodname><link linkend="method-giodatainputstream--read-line">gio.DataInputStream.read_line</link></methodname>(). + It is an error to have two outstanding calls to this function. + </para> + <para> + For the synchronous version of this function, see + <methodname><link linkend="method-giodatainputstream--read-line">gio.DataInputStream.read_line</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was + cancelled, the error gio.ERROR_CANCELLED will be set + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-line-finish"> + <title>gio.DataInputStream.read_line_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_line_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string with the line that was read in (without the newlines). + On an error, it will return <literal>None</literal> and error will be set. + If there's no content to read, it will still return <literal>None</literal>, + but error won't be set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_line_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giodatainputstream--read-line-async">gio.DataInputStream.read_line_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-uint16"> + <title>gio.DataInputStream.read_uint16</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_uint16</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a signed 16-bit/2-byte value read from stream or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_uint16</methodname>() method reads a 16-bit/2-byte value from stream. + </para> + <para> + In order to get the correct byte order for this read operation, see + <methodname><link linkend="method-giodatainputstream--get-byte_order">gio.DataInputStream.get_byte_order</link></methodname>() + and + <methodname><link linkend="method-giodatainputstream--set-byte_order">gio.DataInputStream.set_byte_order</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-uint32"> + <title>gio.DataInputStream.read_uint32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_uint32</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a signed 32-bit/4-byte value read from the stream + or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_uint32</methodname>() method reads a signed 32-bit/4-byte value from stream. + </para> + <para> + In order to get the correct byte order for this read operation, see + <methodname><link linkend="method-giodatainputstream--get-byte_order">gio.DataInputStream.get_byte_order</link></methodname>() + and + <methodname><link linkend="method-giodatainputstream--set-byte_order">gio.DataInputStream.set_byte_order</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-uint64"> + <title>gio.DataInputStream.read_uint64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_uint64</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a signed 64-bit/8-byte value read from the stream + or 0 if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_uint64</methodname>() method reads a signed 64-bit/8-byte value from stream. + </para> + <para> + In order to get the correct byte order for this read operation, see + <methodname><link linkend="method-giodatainputstream--get-byte_order">gio.DataInputStream.get_byte_order</link></methodname>() + and + <methodname><link linkend="method-giodatainputstream--set-byte_order">gio.DataInputStream.set_byte_order</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-until"> + <title>gio.DataInputStream.read_until</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_until</methodname> + <methodparam><parameter role="keyword">stop_chars</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">stop_chars</parameter> :</term> + <listitem><simpara>characters to terminate the read. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string with the data that was read before encountering + any of the stop characters. This function will return NULL on an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_until</methodname>() reads a string from the data input + stream, up to the first occurrence of any of the stop characters. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-until-async"> + <title>gio.DataInputStream.read_until_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_until_async</methodname> + <methodparam><parameter role="keyword">stop_chars</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">stop_chars</parameter> :</term> + <listitem><simpara>characters to terminate the read. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_until_async</methodname>() method it's the asynchronous version of + <methodname><link linkend="method-giodatainputstream--read-until">gio.DataInputStream.read_until</link></methodname>(). + It is an error to have two outstanding calls to this function. + </para> + <para> + For the synchronous version of this function, see + <methodname><link linkend="method-giodatainputstream--read-until">gio.DataInputStream.read_until</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was + cancelled, the error gio.ERROR_CANCELLED will be set + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giodatainputstream--read-until-finish">gio.DataInputStream.read_until_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--read-until-finish"> + <title>gio.DataInputStream.read_until_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_until_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string with the data that was read before encountering + any of the stop characters. This function will return <literal>None</literal> on an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_until_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giodatainputstream--read-until-async">gio.DataInputStream.read_until_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--set-byte-order"> + <title>gio.DataInputStream.set_byte_order</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_byte_order</methodname> + <methodparam><parameter role="keyword">order</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">order</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-data-stream-byte-order-constants" endterm="gio-data-stream-byte-order-constants-title"></xref> to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_byte_order</methodname>() method sets the byte order for + the given stream. All subsequent reads from the stream will be read in the given order. + </para> + </refsect2> + + <refsect2 id="method-giodatainputstream--set-newline-type"> + <title>gio.DataInputStream.set_newline_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_newline_type</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-data-stream-newline-type-constants" endterm="gio-data-stream-newline-type-constants-title"></xref> to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_newline_type</methodname>() method sets the newline type for the stream. + </para> + <note> + Note that using gio.DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a + read chunk ends in "CR" we must read an additional byte to know if this is + "CR" or "CR LF", and this might block if there is no more data availible. + </note> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-dataoutputstream.xml b/docs/reference/pygio-dataoutputstream.xml new file mode 100644 index 0000000..4cbc904 --- /dev/null +++ b/docs/reference/pygio-dataoutputstream.xml @@ -0,0 +1,504 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giodataoutputstream"> + <refnamediv> + <refname>gio.DataOutputStream</refname> + <refpurpose>Data Output Stream</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.DataOutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giobufferedoutputstream">gio.BufferedOutputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giodataoutputstream">gio.DataOutputStream</link></methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--get-byte-order">get_byte_order</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-byte">put_byte</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-int16">put_int16</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-int32">put_int32</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-int64">put_int64</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-string">put_string</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-uint16">put_uint16</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-uint32">put_uint32</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--put-uint64">put_uint64</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodataoutputstream--set-byte-order">set_byte_order</link></methodname> + <methodparam><parameter role="keyword">order</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> + +-- <link linkend="class-giofilteroutputstream">gio.FilterOutputStream</link> + +-- <link linkend="class-giobufferedoutputstream">gio.BufferedOutputStream</link> + +-- <link linkend="class-giodataoutputstream">gio.DataOutputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giodataoutputstream"> + <title>gio.DataOutputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"byte-order"</entry> + <entry>Read - Write</entry> + <entry>Determines the byte ordering that is used when writing + multi-byte entities (such as integers) to the stream. + Default value: gio.DATA_STREAM_BYTE_ORDER_BIG_ENDIAN.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giodataoutputstream"><classname>gio.DataOutputStream</classname></link> + implements <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + and includes functions for writing data directly to an output stream. + </para> + </refsect1> + + <refsect1 id="constructor-giodataoutputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.DataOutputStream</methodname> + <methodparam><parameter role="keyword">base_stream</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>base_stream</parameter> :</term> + <listitem><simpara>a + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giodataoutputstream"><classname>gio.DataOutputStream</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giodataoutputstream"><classname>gio.DataOutputStream</classname></link> + from the given base_stream. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giodataoutputstream--get-byte-order"> + <title>gio.DataOutputStream.get_byte_order</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_byte_order</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the stream's current + <xref linkend="gio-data-stream-byte-order-constants" endterm="gio-data-stream-byte-order-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_byte_order</methodname>() method gets the byte + order for the stream. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-byte"> + <title>gio.DataOutputStream.put_byte</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_byte</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a char. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_byte</methodname>() method puts a byte into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-int16"> + <title>gio.DataOutputStream.put_int16</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_int16</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a gint16. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_int16</methodname>() method puts a signed 16-bit integer into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-int32"> + <title>gio.DataOutputStream.put_int32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_int32</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a gint32. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_int32</methodname>() method puts a signed 32-bit integer into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-int64"> + <title>gio.DataOutputStream.put_int64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_int64</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a gint64. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_int64</methodname>() method puts a signed 64-bit integer into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-string"> + <title>gio.DataOutputStream.put_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_string</methodname> + <methodparam><parameter role="keyword">str</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">str</parameter> :</term> + <listitem><simpara>a string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if string was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_string</methodname>() method puts a string into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-uint16"> + <title>gio.DataOutputStream.put_uint16</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_uint16</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a guint16. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_uint16</methodname>() method puts an unsigned 16-bit integer into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-uint32"> + <title>gio.DataOutputStream.put_uint32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_uint32</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a guint32. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_uint32</methodname>() method puts an unsigned 32-bit integer into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--put-uint64"> + <title>gio.DataOutputStream.put_uint64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>put_uint64</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>a guint64. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if data was successfully added to the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>put_uint64</methodname>() method puts an unsigned 64-bit integer into the output stream. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giodataoutputstream--set-byte-order"> + <title>gio.DataOutputStream.set_byte_order</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_byte_order</methodname> + <methodparam><parameter role="keyword">order</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">order</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-data-stream-byte-order-constants" endterm="gio-data-stream-byte-order-constants-title"></xref> to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_byte_order</methodname>() method sets the byte order for + the given stream. All subsequent reads from the stream will be read in the given order. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-drive.xml b/docs/reference/pygio-drive.xml new file mode 100644 index 0000000..73766cd --- /dev/null +++ b/docs/reference/pygio-drive.xml @@ -0,0 +1,546 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giodrive"> + <refnamediv> + <refname>gio.Drive</refname> + <refpurpose>Virtual File System drive management.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Drive</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--can-eject">can_eject</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--can-poll-for-media">can_poll_for_media</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--eject">eject</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--eject-finish">eject_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--enumerate-identifiers">enumerate_identifiers</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--get-identifier">get_identifier</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--get-name">get_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--get-volumes">get_volumes</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--has-media">has_media</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--has-volumes">has_volumes</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--is-media-check-automatic">is_media_check_automatic</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--is-media-removable">is_media_removable</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--poll-for-media">poll_for_media</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giodrive--poll-for-media-finish">poll_for_media_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-giodrive">gio.Drive</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-giodrive"><classname>gio.Drive</classname></link> requires + <link linkend="class-gobject"><classname>gobject.GObject</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + - this represent a piece of hardware connected to the machine. Its generally + only created for removable hardware or hardware with removable media. + </para> + <para> + <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + is a container class for GVolume objects that stem from the same piece of media. + As such, <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + abstracts a drive with (or without) removable media and provides operations for + querying whether media is available, determing whether media change is automatically + detected and ejecting the media. + </para> + <para> + If the <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + reports that media isn't automatically detected, one can poll for media; typically + one should not do this periodically as a poll for media operation is potententially + expensive and may spin up the drive creating noise. + </para> + <para> + For porting from GnomeVFS note that there is no equivalent of + <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + in that API. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giodrive--can-eject"> + <title>gio.Drive.can_eject</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_eject</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the drive can be ejected, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_eject</methodname>() method checks if a drive can be ejected. + </para> + </refsect2> + + <refsect2 id="method-giodrive--can-poll-for-media"> + <title>gio.Drive.can_poll_for_media</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_poll_for_media</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the drive can be polled + for media changes, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_poll_for_media</methodname>() method checks if a drive + can be polled for media changes. + </para> + </refsect2> + + <refsect2 id="method-giodrive--eject"> + <title>gio.Drive.eject</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject</methodname> + <methodparam> + <parameter role="keyword">callback</parameter> + </methodparam> + <methodparam> + <parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags affecting the unmount if required for eject. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject</methodname>() method asynchronously ejects a drive. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giodrive--eject-finish">gio.Drive.eject_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giodrive--eject-finish"> + <title>gio.Drive.eject_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the drive has been ejected + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject_finish</methodname>() method finishes ejecting a drive. + </para> + </refsect2> + + <refsect2 id="method-giodrive--enumerate-identifiers"> + <title>gio.Drive.enumerate_identifiers</title> + + <programlisting><methodsynopsis language="python"> + <methodname>enumerate_identifiers</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of strings containing kinds of identifiers. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>enumerate_identifiers</methodname>() method gets the kinds + of identifiers that drive has. Use + <methodname><link linkend="method-giodrive--get-identifier">gio.Drive.get_identifier</link></methodname>() + to obtain the identifiers themselves. + </para> + </refsect2> + + <refsect2 id="method-giodrive--get-icon"> + <title>gio.Drive.get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_icon</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><link linkend="class-gioicon"><classname>gio.Icon</classname></link> + for the drive. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_icon</methodname>() method gets the icon for drive. + </para> + </refsect2> + + <refsect2 id="method-giodrive--get-identifier"> + <title>gio.Drive.get_identifier</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_identifier</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A string containing the requested identfier, or + <literal>None</literal> if the + <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + doesn't have this kind of identifier. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_identifier</methodname>() method gets the identifier of + the given kind for drive. + </para> + </refsect2> + + <refsect2 id="method-giodrive--get-name"> + <title>gio.Drive.get_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A string containing drive's name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_name</methodname>() method gets the name of drive. + </para> + </refsect2> + + <refsect2 id="method-giodrive--get-volumes"> + <title>gio.Drive.get_volumes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_volumes</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list containing any + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + objects on the given drive. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_volumes</methodname>() method get a list of mountable + volumes for drive. + </para> + </refsect2> + + <refsect2 id="method-giodrive--has-media"> + <title>gio.Drive.has_media</title> + + <programlisting><methodsynopsis language="python"> + <methodname>has_media</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if drive has media, + <literal>False</literal> otherwise.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>has_media</methodname>() method checks if the drive + has media. Note that the OS may not be polling the drive for media changes; see + <methodname><link linkend="method-giodrive--is-media-check-automatic">gio.Drive.is_media_check_automatic</link></methodname>() + for more details. + </para> + </refsect2> + + <refsect2 id="method-giodrive--has-volumes"> + <title>gio.Drive.has_volumes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>has_volumes</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if drive contains volumes, + <literal>False</literal> otherwise.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>has_volumes</methodname>() method check if drive has any mountable volumes. + </para> + </refsect2> + + <refsect2 id="method-giodrive--is-media-check-automatic"> + <title>gio.Drive.is_media_check_automatic</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_media_check_automatic</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if drive is capabable + of automatically detecting media changes, + <literal>False</literal> otherwise.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>is_media_check_automatic</methodname>() method checks if + drive is capabable of automatically detecting media changes. + </para> + </refsect2> + + <refsect2 id="method-giodrive--is-media-removable"> + <title>gio.Drive.is_media_removable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_media_removable</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if drive supports removable media, + <literal>False</literal> otherwise.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>is_media_removable</methodname>() method checks if the + drive supports removable media. + </para> + </refsect2> + + <refsect2 id="method-giodrive--poll-for-media"> + <title>gio.Drive.poll_for_media</title> + + <programlisting><methodsynopsis language="python"> + <methodname>poll_for_media</methodname> + <methodparam> + <parameter role="keyword">callback</parameter> + </methodparam> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>poll_for_media</methodname>() method asynchronously polls + drive to see if media has been inserted or removed. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giodrive--poll-for-media-finish">gio.Drive.poll_for_media_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giodrive--poll-for-media-finish"> + <title>gio.Drive.poll_for_media_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>poll_for_media_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the drive has been poll_for_mediaed + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>poll_for_media_finish</methodname>() method finishes + an operation started with + <methodname><link linkend="method-giodrive--poll-for-media">gio.Drive.poll_for_media</link></methodname>() + on a drive. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-emblem.xml b/docs/reference/pygio-emblem.xml new file mode 100644 index 0000000..032b0ff --- /dev/null +++ b/docs/reference/pygio-emblem.xml @@ -0,0 +1,232 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioemblem"> + <refnamediv> + <refname>gio.Emblem</refname> + <refpurpose>An object for emblems.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Emblem</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + <ooclass><classname><link linkend="class-gioicon">gio.Icon</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-gioemblem">gio.Emblem</link></methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + <methodparam><parameter role="keyword">origin</parameter><initializer><literal>gio.EMBLEM_ORIGIN_UNKNOWN</literal></initializer></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioemblem--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioemblem--get-origin">get_origin</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--emblem-new-with-origin">gio.emblem_new_with_origin</link></methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + <methodparam><parameter role="keyword">origin</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioemblem">gio.Emblem</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interfaces</title> + <para> + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link> + implements + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + </para> + </refsect1> + + <refsect1 id="properties-gioemblem"> + <title>gio.Emblem Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"icon"</entry> + <entry>Read - Write - Construct Only</entry> + <entry>The actual icon of the emblem.</entry> + </row> + <row valign="top"> + <entry>"origin"</entry> + <entry>Read - Write - Construct Only</entry> + <entry>Tells which origin the emblem is derived from.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link> + class is an implementation of <classname><link linkend="class-gioicon">gio.Icon</link></classname> + that supports having an emblem, which is an icon with additional properties. + It can then be added to a + <link linkend="class-gioemblemedicon"><classname>gio.EmblemedIcon</classname></link>. + </para> + <para> + Currently, only metainformation about the emblem's origin is supported. + More may be added in the future. + </para> + </refsect1> + + <refsect1 id="constructor-gioemblem"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.Emblem</methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + <methodparam><parameter role="keyword">origin</parameter><initializer><literal>gio.EMBLEM_ORIGIN_UNKNOWN</literal></initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>icon</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> containing the icon. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>origin</parameter> :</term> + <listitem><simpara> + <link linkend="gio-emblem-origin-constants">origin</link> of the emblem. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <note> + Parameter <parameter>origin</parameter> is available since PyGObject 2.20. + </note> + + <para> + Creates a new <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link> for icon. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioemblem--get-icon"> + <title>gio.Emblem.get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_icon</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_icon</methodname>() method gives back the icon from emblem. + </para> + </refsect2> + + <refsect2 id="method-gioemblem--get-origin"> + <title>gio.Emblem.get_origin</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_origin</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the origin of the emblem. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_origin</methodname>() method gets the origin of the emblem. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--emblem-new-with-origin"> + <title>gio.emblem_new_with_origin</title> + + <programlisting><methodsynopsis language="python"> + <methodname>emblem_new_with_origin</methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + <methodparam><parameter role="keyword">origin</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>origin</parameter> :</term> + <listitem><simpara>a <xref linkend="gio-emblem-origin-constants" endterm="gio-emblem-origin-constants-title"></xref> + defining the emblem's origin. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <note> + While this method is not deprecated, with 2.20 and up it is recommended + to use the constructor instead. + </note> + + + <para> + The <methodname>emblem_new_with_origin</methodname>() function creates + a new emblem for icon. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-emblemedicon.xml b/docs/reference/pygio-emblemedicon.xml new file mode 100644 index 0000000..9b5ef8a --- /dev/null +++ b/docs/reference/pygio-emblemedicon.xml @@ -0,0 +1,160 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioemblemedicon"> + <refnamediv> + <refname>gio.EmblemedIcon</refname> + <refpurpose>Icon with emblems.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.EmblemedIcon</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + <ooclass><classname><link linkend="class-gioicon">gio.Icon</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-gioemblemedicon">gio.EmblemedIcon</link></methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + <methodparam><parameter role="keyword">emblem</parameter></methodparam> + </constructorsynopsis> + + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioemblemedicon--add-emblem">add_emblem</link></methodname> + <methodparam><parameter role="keyword">emblem</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioemblemedicon--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioemblemedicon">gio.EmblemedIcon</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interfaces</title> + <para> + <link linkend="class-gioemblemedicon"><classname>gio.EmblemedIcon</classname></link> + implements + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-gioemblemedicon"><classname>gio.EmblemedIcon</classname></link> + class is an implementation of <classname><link linkend="class-gioicon">gio.Icon</link></classname> + that supports adding an emblem to an icon. Adding multiple emblems to an icon is ensured via + <methodname><link linkend="method-gioemblemedicon--add-emblem">gio.EmblemedIcon.add_emblem</link></methodname>(). + </para> + <para> + Note that + <link linkend="class-gioemblemedicon"><classname>gio.EmblemedIcon</classname></link> + allows no control over the position of the emblems. See also + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link> + for more information. + </para> + </refsect1> + + <refsect1 id="constructor-gioemblemedicon"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.EmblemedIcon</methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + <methodparam><parameter role="keyword">emblem</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>icon</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>emblem</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-gioicon"><classname>gio.Icon</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + for icon with the emblem emblem. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioemblemedicon--add-emblem"> + <title>gio.EmblemedIcon.add_emblem</title> + + <programlisting><methodsynopsis language="python"> + <methodname>add_emblem</methodname> + <methodparam><parameter role="keyword">emblem</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>emblem</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>add_emblem</methodname>() method adds emblem to the + list of <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link>s. + </para> + </refsect2> + + <refsect2 id="method-gioemblemedicon--get-icon"> + <title>gio.EmblemedIcon.get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_icon</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + that is owned by emblemed. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_icon</methodname>() method gets the main icon for emblemed. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-file.xml b/docs/reference/pygio-file.xml new file mode 100644 index 0000000..ac85840 --- /dev/null +++ b/docs/reference/pygio-file.xml @@ -0,0 +1,4534 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofile"> + <refnamediv> + <refname>gio.File</refname> + <refpurpose>File and Directory Handling.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.File</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giofile">gio.File</link></methodname> + <methodparam><parameter role="keyword">commandline</parameter></methodparam> + <methodparam><parameter role="keyword">path</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">uri</parameter><initializer>None</initializer></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--append-to">append_to</link></methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--append-to-async">append_to_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--append-to-finish">append_to_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--copy">copy</link></methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">progress_callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--copy-async">copy_async</link></methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">progress_callback</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">progress_callback_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--copy-attributes">copy_attributes</link></methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--copy-finish">copy_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--create">create</link></methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--create-async">create_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--create-finish">create_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--delete">delete</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--dup">dup</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--eject-mountable">eject_mountable</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--eject-mountable-finish">eject_mountable_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--enumerate-children">enumerate_children</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--enumerate-children-async">enumerate_children_async</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--enumerate-children-finish">enumerate_children_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--equal">equal</link></methodname> + <methodparam><parameter role="keyword">file2</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--find-enclosing-mount">find_enclosing_mount</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--find-enclosing-mount-async">find_enclosing_mount_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--find-enclosing-mount-finish">find_enclosing_mount_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-basename">get_basename</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-child">get_child</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-child-for-display-name">get_child_for_display_name</link></methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-parent">get_parent</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-parse-name">get_parse_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-path">get_path</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-relative-path">get_relative_path</link></methodname> + <methodparam><parameter role="keyword">descendant</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-uri">get_uri</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--get-uri-scheme">get_uri_scheme</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--has-prefix">has_prefix</link></methodname> + <methodparam><parameter role="keyword">prefix</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--has-uri-scheme">has_uri_scheme</link></methodname> + <methodparam><parameter role="keyword">uri_scheme</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--is-native">is_native</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--load-contents">load_contents</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--load-contents-async">load_contents_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--load-contents-finish">load_contents_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--make-directory">make_directory</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--make-directory-with-parents">make_directory_with_parents</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--make-symbolic-link">make_symbolic_link</link></methodname> + <methodparam><parameter role="keyword">symlink_value</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--monitor">monitor</link></methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--monitor-directory">monitor_directory</link></methodname> + <methodparam><parameter role="keyword">flags</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--monitor-file">monitor_file</link></methodname> + <methodparam><parameter role="keyword">flags</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-enclosing-volume">mount_enclosing_volume</link></methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.MOUNT_MOUNT_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-enclosing-volume-finish">mount_enclosing_volume_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-mountable">mount_mountable</link></methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.MOUNT_MOUNT_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--mount-mountable-finish">mount_mountable_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--move">move</link></methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">progress_callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-default-handler">query_default_handler</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-exists">query_exists</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-file-type">query_file_type</link></methodname> + <methodparam><parameter role="keyword">flags</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-filesystem-info">query_filesystem_info</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-filesystem-info-async">query_filesystem_info_async</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-filesystem-info-finish">query_filesystem_info_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-info">query_info</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-info-async">query_info_async</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-info-finish">query_info_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-settable-attributes">query_settable_attributes</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--query-writable-namespace">query_writable_namespace</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--read">read</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--read-async">read_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--read-finish">read_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace">replace</link></methodname> + <methodparam><parameter role="keyword">etag</parameter></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-async">replace_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-contents">replace_contents</link></methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-contents-async">replace_contents_async</link></methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-contents-finish">replace_contents_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--replace-finish">replace_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--resolve-relative-path">resolve_relative_path</link></methodname> + <methodparam><parameter role="keyword">relative_path</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute">set_attribute</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">value_p</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-byte-string">set_attribute_byte_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-int32">set_attribute_int32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-int64">set_attribute_int64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-string">set_attribute_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-uint32">set_attribute_uint32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attribute-uint64">set_attribute_uint64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attributes-async">set_attributes_async</link></methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attributes-finish">set_attributes_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-attributes-from-info">set_attributes_from_info</link></methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-display-name">set_dispay_name</link></methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-display-name-async">set_display_name_async</link></methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--set-display-name-finish">set_display_name_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--trash">trash</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--unmount-mountable">unmount_mountable</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.MOUNT_UNMOUNT_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofile--unmount-mountable-finish">unmount_mountable_finish</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--file-parse-name">gio.file_parse_name</link></methodname> + <methodparam><parameter role="keyword">parse_name</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-giofile">gio.File</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-giofile"><classname>gio.File</classname></link> is implemented by + <link linkend="class-gobject"><classname>gobject.GObject</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giofile"><classname>gio.File</classname></link> is a high + level abstraction for manipulating files on a virtual file system. + <link linkend="class-giofile"><classname>gio.File</classname></link>s are lightweight, + immutable objects that do no I/O upon creation. It is necessary to understand that + <link linkend="class-giofile"><classname>gio.File</classname></link> + objects do not represent files, merely an identifier for a file. All file content + I/O is implemented as streaming operations (see + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> and + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>). + </para> + <para> + To construct a <link linkend="class-giofile"><classname>gio.File</classname></link>, you can use + it's constructor either with a path, an uri or a commandline argument. + <methodname><link linkend="function-gio--file-parse-name">gio.file_parse_name</link></methodname>() + from a utf8 string gotten from + <methodname><link linkend="method-giofile--get-parse-name">gio.File.get_parse_name</link></methodname>(). + </para> + <para> + One way to think of a <link linkend="class-giofile"><classname>gio.File</classname></link> is as + an abstraction of a pathname. For normal files the system pathname is what is stored internally, + but as <link linkend="class-giofile"><classname>gio.File</classname></link>s are extensible it + could also be something else that corresponds to a pathname in a userspace implementation of a filesystem. + </para> + <para> + <link linkend="class-giofile"><classname>gio.File</classname></link>s make up hierarchies of + directories and files that correspond to the files on a filesystem. You can move through the + file system with GFile using + <methodname><link linkend="method-giofile--get-parent">gio.File.get_parent</link></methodname>() + to get an identifier for the parent directory, + <methodname><link linkend="method-giofile--get-child">gio.File.get_child</link></methodname>() + to get a child within a directory, + <methodname><link linkend="method-giofile--resolve-relative-path">gio.File.resolve_relative_path</link></methodname>() + to resolve a relative path between two <link linkend="class-giofile"><classname>gio.File</classname></link>s. + There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call + <methodname><link linkend="method-giofile--get-parent">gio.File.get_parent</link></methodname>() + on two different files. + </para> + <para> + All <link linkend="class-giofile"><classname>gio.File</classname></link>s have a basename (get with + <methodname><link linkend="method-giofile--get-basename">gio.File.get_basename</link></methodname>() + ). These names are byte strings that are used to identify the file on the filesystem + (relative to its parent directory) and there is no guarantees that they have any particular charset + encoding or even make any sense at all. If you want to use filenames in a user interface you should + use the display name that you can get by requesting the gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with + <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>(). + This is guaranteed to be in utf8 and can be used in a user interface. But always store the real basename or the + GFile to use to actually access the file, because there is no way to go from a display name to the actual name. + </para> + <para> + Using <link linkend="class-giofile"><classname>gio.File</classname></link> as an identifier has the same + weaknesses as using a path in that there may be multiple aliases for the same file. For instance, + hard or soft links may cause two different <link linkend="class-giofile"><classname>gio.File</classname></link>s + to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and + long names on Fat/NTFS, or bind mounts in Linux. If you want to check if two GFiles point to the same file + you can query for the gio.FILE_ATTRIBUTE_ID_FILE attribute. Note that + <link linkend="class-giofile"><classname>gio.File</classname></link> does some trivial canonicalization + of pathnames passed in, so that trivial differences in the path string used at creation + (duplicated slashes, slash at end of path, "." or ".." path segments, etc) does not create different + <link linkend="class-giofile"><classname>gio.File</classname></link>s. + </para> + <para> + Many <link linkend="class-giofile"><classname>gio.File</classname></link> operations have both synchronous + and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply + have _async() appended to their function names. The asynchronous I/O functions call a + GAsyncReadyCallback which is then used to finalize the operation, producing a GAsyncResult + which is then passed to the function's matching _finish() operation. + </para> + <para> + Some <link linkend="class-giofile"><classname>gio.File</classname></link> operations do not have + synchronous analogs, as they may take a very long time to finish, and blocking may leave an application + unusable. Notable cases include: + <methodname><link linkend="method-giofile--mount-mountable">gio.File.mount_mountable</link></methodname>() + to mount a mountable file. + <methodname><link linkend="method-giofile--unmount-mountable">gio.File.unmount_mountable</link></methodname>() + to unmount a mountable file. + <methodname><link linkend="method-giofile--eject-mountable">gio.File.eject_mountable</link></methodname>() + to eject a mountable file. + </para> + <para> + One notable feature of <link linkend="class-giofile"><classname>gio.File</classname></link>s are + entity tags, or "etags" for short. Entity tags are somewhat like a more abstract + version of the traditional mtime, and can be used to quickly determine if the file + has been modified from the version on the file system. See the HTTP 1.1 + specification for HTTP Etag headers, which are a very similar concept. + </para> + </refsect1> + + <refsect1 id="constructor-giofile"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.File</methodname> + <methodparam><parameter role="keyword">commandline</parameter></methodparam> + <methodparam><parameter role="keyword">path</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">uri</parameter><initializer>None</initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>commandline</parameter> :</term> + <listitem><simpara>a command line string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>path</parameter> :</term> + <listitem><simpara>a string containing a relative or absolute path. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>uri</parameter> :</term> + <listitem><simpara>a string containing a URI. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giofile"><classname>gio.File</classname></link> either from a commandline, + a path or an uri. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofile--append-to"> + <title>gio.File.append_to</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>append_to</methodname>() method gets an output stream for + appending data to the file. If the file doesn't already exist it is created. + </para> + <para> + By default files created are generally readable by everyone, but if you pass + gio.FILE_CREATE_PRIVATE in flags the file will be made readable only to the + current user, to the level that is supported on the target filesystem. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If + the operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + Some file systems don't allow all file names, and may return an + gio.ERROR_INVALID_FILENAME error. If the file is a directory the + gio.ERROR_IS_DIRECTORY error will be returned. Other errors are possible too, + and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--append-to-async"> + <title>gio.File.append_to_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>append_to_async</methodname>() method asynchronously opens file for appending. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--append-to">gio.File.append_to</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--append-to-finish">gio.File.append_to_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--append-to-finish"> + <title>gio.File.append_to_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a valid + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>append_to_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giofile--append-to-async">gio.File.append_to_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--copy"> + <title>gio.File.copy</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy</methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">progress_callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>destination</parameter> :</term> + <listitem><simpara>destination <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>progress_callback</parameter> :</term> + <listitem><simpara>function to callback with progress information. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to the progress callback function. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on success, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy</methodname>() method copies the file source to + the location specified by destination. Can not handle recursive copies of directories. + </para> + <para> + If the flag gio.FILE_COPY_OVERWRITE is specified an already existing + destination file is overwritten. + </para> + <para> + If the flag gio.FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will + be copied as symlinks, otherwise the target of the source symlink will be copied. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + If progress_callback is not <literal>None</literal>, then the operation can be + monitored by setting this to a GFileProgressCallback function. user_data + will be passed to this function. It is guaranteed that this callback will be + called after all data has been transferred with the total number of bytes + copied during the operation. + </para> + <para> + If the source file does not exist then the gio.ERROR_NOT_FOUND error is returned, + independent on the status of the destination. + </para> + <para> + If gio.FILE_COPY_OVERWRITE is not specified and the target exists, + then the error gio.ERROR_EXISTS is returned. + </para> + <para> + If trying to overwrite a file over a directory the gio.ERROR_IS_DIRECTORY error + is returned. If trying to overwrite a directory with a directory the + gio.ERROR_WOULD_MERGE error is returned. + </para> + <para> + If the source is a directory and the target does not exist, or gio.FILE_COPY_OVERWRITE + is specified and the target is a file, then the gio.ERROR_WOULD_RECURSE error is returned. + </para> + <para> + If you are interested in copying the + <link linkend="class-giofile"><classname>gio.File</classname></link> object + itself (not the on-disk file), see + <methodname><link linkend="method-giofile--dup">gio.File.dup</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--copy-async"> + <title>gio.File.copy_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_to_async</methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">progress_callback</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">progress_callback_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>destination</parameter> :</term> + <listitem><simpara>destination <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>progress_callback</parameter> :</term> + <listitem><simpara>function to callback with progress information. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>progress_callback_data</parameter> :</term> + <listitem><simpara>the data to pass to the progress callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy_async</methodname>() method copies the file source to + the location specified by destination asynchronously. For details of the behaviour, + see <methodname><link linkend="method-giofile--copy">gio.File.copy</link></methodname>(). + </para> + <para> + If progress_callback is not <literal>None</literal>, then that function that will + be called just like in + <methodname><link linkend="method-giofile--copy">gio.File.copy</link></methodname>(), + however the callback will run in the main loop, not in the thread that is doing the I/O operation. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--copy-finish">gio.File.copy_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--copy-attributes"> + <title>gio.File.copy_attributes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy_attributes</methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>destination</parameter> :</term> + <listitem><simpara>destination <link linkend="class-giofile"><classname>gio.File</classname></link> + to copy attributes to. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attributes were copied successfully, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy_attributes</methodname>() method copies the file attributes + from source to destination. + </para> + <para> + Normally only a subset of the file attributes are copied, those that are copies + in a normal file copy operation (which for instance does not include e.g. owner). + However if gio.FILE_COPY_ALL_METADATA is specified in flags, then all the metadata + that is possible to copy is copied. This is useful when implementing move by copy + delete source. + </para> + </refsect2> + + <refsect2 id="method-giofile--copy-finish"> + <title>gio.File.copy_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on success, + <literal>False</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>copy_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--copy-async">gio.File.copy_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--create"> + <title>gio.File.create</title> + + <programlisting><methodsynopsis language="python"> + <methodname>create</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>create</methodname>() method creates a new file and returns + an output stream for writing to it. The file must not already exist. + </para> + <para> + By default files created are generally readable by everyone, but if you pass + gio.FILE_CREATE_PRIVATE in flags the file will be made readable only to the + current user, to the level that is supported on the target filesystem. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + If a file or directory with this name already exists the gio.ERROR_EXISTS + error will be returned. Some file systems don't allow all file names, and + may return an gio.ERROR_INVALID_FILENAME error, and if the name is to long + gio.ERROR_FILENAME_TOO_LONG will be returned. Other errors are possible too, + and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--create-async"> + <title>gio.File.create_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>create_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>create_async</methodname>() method asynchronously creates a new + file and returns an output stream for writing to it. The file must not already exist. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--create">gio.File.create</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--create-finish">gio.File.create_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--create-finish"> + <title>gio.File.create_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>create_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>create_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--create-async">gio.File.create_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--delete"> + <title>gio.File.delete</title> + + <programlisting><methodsynopsis language="python"> + <methodname>delete</methodname> + <methodparam><parameter role="keyword">cancellable</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the file was deleted, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>deleted</methodname>() method deletes a file. If the file is a + directory, it will only be deleted if it is empty. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was + cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--dup"> + <title>gio.File.dup</title> + + <programlisting><methodsynopsis language="python"> + <methodname>dup</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link linkend="class-giofile"><classname>gio.File</classname></link> + that is a duplicate of the given <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>dup</methodname>() method duplicates a + <link linkend="class-giofile"><classname>gio.File</classname></link> + handle. This operation does not duplicate the actual file or directory represented + by the <link linkend="class-giofile"><classname>gio.File</classname></link>; see + <methodname><link linkend="method-giofile--copy">gio.File.copy</link></methodname>() + if attempting to copy a file. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--eject-mountable"> + <title>gio.File.eject_mountable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject_mountable</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject_mountable</methodname>() method starts an asynchronous eject on a + mountable. When this operation has completed, callback will be called with + user_user data, and the operation can be finalized with + <methodname><link linkend="method-giofile--eject-mountable-finish">gio.File.eject_mountable_finish</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--eject-mountable-finish"> + <title>gio.File.eject_mountable_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject_mountable_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the file was ejected successfully, + <literal>False</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>create_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--create-async">gio.File.create_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--enumerate-children"> + <title>gio.File.enumerate_children</title> + + <programlisting><methodsynopsis language="python"> + <methodname>enumerate_children</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attributes</parameter> :</term> + <listitem><simpara>an attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>enumerate_children</methodname>() method gets the requested information + about the files in a directory. The result is a GFileEnumerator object that will give out + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> objects + for all the files in the directory. + </para> + <para> + The attribute value is a string that specifies the file attributes that should be gathered. + It is not an error if it's not possible to read a particular requested attribute from a file - + it just won't be set. attribute should be a comma-separated list of attribute or attribute + wildcards. The wildcard "*" means all attributes, and a wildcard like "standard::*" means all + attributes in the standard namespace. An example attribute query be "standard::*,owner::user". + The standard attributes are available as defines, like gio.FILE_ATTRIBUTE_STANDARD_NAME. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. If the file + is not a directory, the gio.FILE_ERROR_NOTDIR error will be returned. + Other errors are possible too. + </para> + </refsect2> + + <refsect2 id="method-giofile--enumerate-children-async"> + <title>gio.File.enumerate_children_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>enumerate_children_async</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attributes</parameter> :</term> + <listitem><simpara>an attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>enumerate_children_async</methodname>() method asynchronously gets the + requested information about the files in a directory. The result is a + <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + object that will give out <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + objects for all the files in the directory. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--enumerate-children">enumerate_children</link></methodname>() + which is the synchronous version of this call. + </para> + </refsect2> + + <refsect2 id="method-giofile--enumerate-children-finish"> + <title>gio.File.eject_mountable_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>enumerate_children_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>enumerate_children_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--enumerate-children-async">gio.File.enumerate_children_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--equal"> + <title>gio.File.equal</title> + + <programlisting><methodsynopsis language="python"> + <methodname>equal</methodname> + <methodparam><parameter role="keyword">file2</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">file2</parameter> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if file1 and file2 are equal. + <literal>False</literal> if either is not a + <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>equal</methodname>() method checks equality of two given + <link linkend="class-giofile"><classname>gio.File</classname></link>s. + Note that two <link linkend="class-giofile"><classname>gio.File</classname></link>s + that differ can still refer to the same file on the filesystem due to various + forms of filename aliasing. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--find-enclosing-mount"> + <title>gio.File.find_enclosing_mount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>enumerate_children</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>find_enclosing_mount</methodname>() method gets a + <link linkend="class-giomount"><classname>gio.Mount</classname></link> for the + <link linkend="class-giofile"><classname>gio.File</classname></link>. + </para> + <para> + If the interface for file does not have a mount (e.g. possibly a remote share), + error will be set to gio.ERROR_NOT_FOUND and <literal>None</literal> will be returned. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--find-enclosing-mount-async"> + <title>gio.File.find_enclosing_mount_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>find_enclosing_mount_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>find_enclosing_mount_async</methodname>() method asynchronously + gets the mount for the file. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--find-enclosing-mount">gio.File.find_enclosing_mount</link></methodname>() + which is the synchronous version of this call. + </para> + </refsect2> + + <refsect2 id="method-giofile--find-enclosing-mount-finish"> + <title>gio.File.find_enclosing_mount_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>find_enclosing_mount_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giomount"><classname>gio.Mount</classname></link> + or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>find_enclosing_mount_finish</methodname>() method finishes an asynchronous + find mount started with + <methodname><link linkend="method-giofile--find-enclosing-mount-async">gio.File.find_enclosing_mount_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--get-basename"> + <title>gio.File.get_basename</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_basename</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>string containing the + <link linkend="class-giofile"><classname>gio.File</classname></link>'s + base name, or <literal>None</literal> if given + <link linkend="class-giofile"><classname>gio.File</classname></link> is invalid. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_basename</methodname>() method gets the base name + (the last component of the path) for a given + <link linkend="class-giofile"><classname>gio.File</classname></link>. + </para> + <para> + If called for the top level of a system (such as the filesystem root or + a uri like sftp://host/) it will return a single directory separator + (and on Windows, possibly a drive letter). + </para> + <para> + The base name is a byte string (*not* UTF-8). It has no defined encoding + or rules other than it may not contain zero bytes. If you want to use filenames + in a user interface you should use the display name that you can get by requesting + the gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME attribute with + <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>(). + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-child"> + <title>gio.File.get_child</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_child</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>string containing the child's basename. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofile"><classname>gio.File</classname></link> + to a child specified by name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_child</methodname>() method gets a child of file + with basename equal to name. + </para> + <para> + Note that the file with that specific name might not exist, but you can + still have a <link linkend="class-giofile"><classname>gio.File</classname></link> + that points to it. You can use this for instance to create that file. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-child-for-display-name"> + <title>gio.File.get_child_for_display_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_child_for_display_name</methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">display_name</parameter> :</term> + <listitem><simpara>string to a possible child. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofile"><classname>gio.File</classname></link> + to the specified child or <literal>None</literal> + if the display name couldn't be converted. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_child_for_display_name</methodname>() method gets the + child of file for a given display_name (i.e. a UTF8 version of the name). + If this function fails, it returns NULL and error will be set. This is very + useful when constructing a GFile for a new file and the user entered the filename + in the user interface, for instance when you select a directory and type a filename + in the file selector. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-parent"> + <title>gio.File.get_parent</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_parent</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofile"><classname>gio.File</classname></link> + structure to the parent of the given + <link linkend="class-giofile"><classname>gio.File</classname></link> or + <literal>None</literal> if there is no parent. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_parent</methodname>() method gets the parent directory for the file. + If the file represents the root directory of the file system, then <literal>None</literal> + will be returned. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-parse-name"> + <title>gio.File.get_parse_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_parse_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the + <link linkend="class-giofile"><classname>gio.File</classname></link>'s parse name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_parse_name</methodname>() method gets the parse name + of the file. A parse name is a UTF-8 string that describes the file such + that one can get the <link linkend="class-giofile"><classname>gio.File</classname></link> + back using + <methodname><link linkend="function-gio--file-parse-name">gio.file_parse_name</link></methodname>(). + </para> + <para> + This is generally used to show the <link linkend="class-giofile"><classname>gio.File</classname></link> + as a nice full-pathname kind of string in a user interface, like in a location entry. + </para> + <para> + For local files with names that can safely be converted to UTF8 the pathname is used, + otherwise the IRI is used (a form of URI that allows UTF8 characters unescaped). + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-path"> + <title>gio.File.get_path</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_path</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the + <link linkend="class-giofile"><classname>gio.File</classname></link>'s path, + or <literal>None</literal> if no such path exists. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_path</methodname>() method gets the local pathname for + <link linkend="class-giofile"><classname>gio.File</classname></link>, if one exists. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-relative-path"> + <title>gio.File.get_relative_path</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_relative_path</methodname> + <methodparam><parameter role="keyword">descendant</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">descendant</parameter> :</term> + <listitem><simpara>input <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>string with the relative path from descendant to parent, + or <literal>None</literal> if descendant doesn't have parent as prefix. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_relative_path</methodname>() method gets the path for + descendant relative to parent. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-uri"> + <title>gio.File.get_uri</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_uri</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the + <link linkend="class-giofile"><classname>gio.File</classname></link>'s URI. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_uri</methodname>() method gets the URI for the file. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--get-uri-scheme"> + <title>gio.File.get_uri_scheme</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_uri_scheme</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the URI scheme for the + <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_uri_scheme</methodname>() method gets the URI scheme for a + <link linkend="class-giofile"><classname>gio.File</classname></link>. + RFC 3986 decodes the scheme as: + </para> +<programlisting> +URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] +</programlisting> + <para> + Common schemes include "file", "http", "ftp", etc. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--has-prefix"> + <title>gio.File.has_prefix</title> + + <programlisting><methodsynopsis language="python"> + <methodname>has_prefix</methodname> + <methodparam><parameter role="keyword">prefix</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">prefix</parameter> :</term> + <listitem><simpara>input <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the files's parent, grandparent, + etc is prefix. <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>has_prefix</methodname>() method checks whether file has the prefix + specified by prefix. In other word, if the names of inital elements of files pathname + match prefix. Only full pathname elements are matched, so a path like /foo is not + considered a prefix of /foobar, only of /foo/bar. + </para> + <para> + This call does no blocking i/o, as it works purely on names. As such it can sometimes + return <literal>False</literal> even if file is inside a prefix (from a filesystem point + of view), because the prefix of file is an alias of prefix. + </para> + </refsect2> + + <refsect2 id="method-giofile--has-uri-scheme"> + <title>gio.File.has_uri_scheme</title> + + <programlisting><methodsynopsis language="python"> + <methodname>has_uri_scheme</methodname> + <methodparam><parameter role="keyword">uri_scheme</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">uri_scheme</parameter> :</term> + <listitem><simpara>a string containing a URI scheme. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if + <link linkend="class-giofile"><classname>gio.File</classname></link>'s + backend supports the given URI scheme, <literal>False</literal> if URI scheme + is <literal>None</literal>, not supported, or + <link linkend="class-giofile"><classname>gio.File</classname></link> is invalid. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>has_uri_scheme</methodname>() method checks to see if a + <link linkend="class-giofile"><classname>gio.File</classname></link> + has a given URI scheme. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--is-native"> + <title>gio.File.is_native</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_native</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if file is native. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>is_native</methodname>() method checks to see if a file + is native to the platform. + </para> + <para> + A native file s one expressed in the platform-native filename format, e.g. + "C:\Windows" or "/usr/bin/". This does not mean the file is local, as it + might be on a locally mounted remote filesystem. + </para> + <para> + On some systems non-native files may be available using the native filesystem + via a userspace filesystem (FUSE), in these cases this call will return + <literal>False</literal>, but + <methodname><link linkend="method-giofile--get-path">gio.File.get_path</link></methodname>() + will still return a native path. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--load-contents"> + <title>gio.File.load_contents</title> + + <programlisting><methodsynopsis language="python"> + <methodname>load_contents</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a three tuple containing the contents of the file, + the length of the contents of the file and the current entity tag for the file. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>load_contents</methodname>() method loads the content of the file into memory. + The data is always zero-terminated, but this is not included in the resultant length. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--load-contents-async"> + <title>gio.File.load_contents_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>load_contents_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>load_contents_async</methodname>() method starts an asynchronous load of the file's contents. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--load-contents">gio.File.load_contents</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the load operation has completed, callback will be called with user data. To finish + the operation, call + <methodname><link linkend="method-giofile--load-contents-finish">gio.File.load_contents_finish</link></methodname>() + with the GAsyncResult returned by the callback. + </para> + </refsect2> + + <refsect2 id="method-giofile--load-contents-finish"> + <title>gio.File.load_contents_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>load_contents_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a three tuple containing the contents of the file, + the length of the contents of the file and the current entity tag for the file. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>load_contents_finish</methodname>() method finishes an asynchronous + find mount started with + <methodname><link linkend="method-giofile--load-contents-async">gio.File.load_contents_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--make-directory"> + <title>gio.File.make_directory</title> + + <programlisting><methodsynopsis language="python"> + <methodname>make_directory</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on successful creation, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>make_directory</methodname>() method creates a directory. + Note that this will only create a child directory of the immediate parent directory + of the path or URI given by the <link linkend="class-giofile"><classname>gio.File</classname></link>. + To recursively create directories, see + <methodname><link linkend="method-giofile--make-directory-with-parents">gio.File.make_directory_with_parents</link></methodname>(). + This function will fail if the parent directory does not exist, setting error to + gio.ERROR_NOT_FOUND. If the file system doesn't support creating directories, this + function will fail, setting error to gio.ERROR_NOT_SUPPORTED. + </para> + <para> + For a local <link linkend="class-giofile"><classname>gio.File</classname></link> the newly + created directory will have the default (current) ownership and permissions of the current process. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--make-directory-with-parents"> + <title>gio.File.make_directory_with_parents</title> + + <programlisting><methodsynopsis language="python"> + <methodname>make_directory_with_parents</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if all directories have been successfully created, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>make_directory_with_parents</methodname>() method creates a directory + and any parent directories that may not exist similar to 'mkdir -p'. If the file system + does not support creating directories, this function will fail, setting error to gio.ERROR_NOT_SUPPORTED. + </para> + <para> + For a local <link linkend="class-giofile"><classname>gio.File</classname></link> the newly + created directories will have the default (current) ownership and permissions of the current process. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--make-symbolic-link"> + <title>gio.File.make_symbolic_link</title> + + <programlisting><methodsynopsis language="python"> + <methodname>make_symbolic_link</methodname> + <methodparam><parameter role="keyword">symlink_value</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>symlink_value</parameter> :</term> + <listitem><simpara>a string with the value of the new symlink.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on the creation of a new symlink, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>make_symbolic_link</methodname>() method creates a symbolic link. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--monitor"> + <title>gio.File.monitor</title> + + <programlisting><methodsynopsis language="python"> + <methodname>monitor</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara> + a <xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link> + for the given file, or <literal>None</literal> on error + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>monitor</methodname>() method obtains a file or directory + monitor for the given file, depending on the type of the file. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--monitor-directory"> + <title>gio.File.monitor_directory</title> + + <programlisting><methodsynopsis language="python"> + <methodname>monitor_directory</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara> + a <xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link> + for the given file, or <literal>None</literal> on error + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>monitor_directory</methodname>() method obtains a directory monitor + for the given file. This may fail if directory monitoring is not supported. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--monitor-file"> + <title>gio.File.monitor_file</title> + + <programlisting><methodsynopsis language="python"> + <methodname>monitor_file</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara> + a <xref linkend="gio-file-monitor-flags-constants" endterm="gio-file-monitor-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link> + for the given file, or <literal>None</literal> on error + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>monitor_file</methodname>() method obtains a file monitor for the + given file. If no file notification mechanism exists, then regular polling + of the file is used. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--mount-enclosing-volume"> + <title>gio.File.mount_enclosing_volume</title> + + <programlisting><methodsynopsis language="python"> + <methodname>mount_enclosing_volume</methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mount_operation</parameter> :</term> + <listitem><simpara>a + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + or <literal>None</literal> to avoid user interaction. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request + is satisfied, or <literal>None</literal>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to the progress callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>mount_enclosing_volume</methodname>() method starts a mount_operation, + mounting the volume that contains the file location. + </para> + <para> + When this operation has completed, callback will be called with user_user data, + and the operation can be finalized with + <methodname><link linkend="method-giofile--mount-enclosing-volume-finish">gio.File.mount_enclosing_volume_finish</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--mount-enclosing-volume-finish"> + <title>gio.File.mount_enclosing_volume_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>mount_enclosing_volume_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if successful. If an error has occurred, + this function will return <literal>False</literal> and set error appropriately if present. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>mount_enclosing_volume_finish</methodname>() method finishes an asynchronous + find mount started with + <methodname><link linkend="method-giofile--mount-enclosing-volume">gio.File.mount_enclosing_volume</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--mount-mountable"> + <title>gio.File.mount_mountable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>mount_mountable</methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mount_operation</parameter> :</term> + <listitem><simpara>a + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + or <literal>None</literal> to avoid user interaction. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request + is satisfied, or <literal>None</literal>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-mount-mount-flags-constants" endterm="gio-mount-mount-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to the progress callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>mount_mountable</methodname>() method mounts a file of type + gio.FILE_TYPE_MOUNTABLE. Using mount_operation, you can request callbacks when, + for instance, passwords are needed during authentication. + </para> + <para> + When this operation has completed, callback will be called with user_user data, + and the operation can be finalized with + <methodname><link linkend="method-giofile--mount-mountable-finish">gio.File.mount_mountable_finish</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--mount-mountable-finish"> + <title>gio.File.mount_mountable_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>mount_mountable_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>mount_mountable_finish</methodname>() method finishes an asynchronous + find mount started with + <methodname><link linkend="method-giofile--mount-mountable">gio.File.mount_mountable</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--move"> + <title>gio.File.move</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy</methodname> + <methodparam><parameter role="keyword">destination</parameter></methodparam> + <methodparam><parameter role="keyword">progress_callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_COPY_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>destination</parameter> :</term> + <listitem><simpara>destination <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>progress_callback</parameter> :</term> + <listitem><simpara>function to callback with progress information. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-copy-flags-constants" endterm="gio-file-copy-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to the progress callback function. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on success, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>move</methodname>() method tries to move the file or directory + source to the location specified by destination. If native move operations are + supported then this is used, otherwise a copy + delete fallback is used. The native + implementation may support moving directories (for instance on moves inside the same + filesystem), but the fallback code does not. + </para> + <para> + If the flag gio.FILE_COPY_OVERWRITE is specified an already existing destination file is overwritten. + </para> + <para> + If the flag gio.FILE_COPY_NOFOLLOW_SYMLINKS is specified then symlinks will be copied + as symlinks, otherwise the target of the source symlink will be copied. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + If progress_callback is not <literal>None</literal>, then the operation can be monitored + by setting this to a GFileProgressCallback function. progress_callback_data will be passed + to this function. It is guaranteed that this callback will be called after all data has been + transferred with the total number of bytes copied during the operation. + </para> + <para> + If the source file does not exist then the gio.ERROR_NOT_FOUND error is returned, + independent on the status of the destination. + </para> + <para> + If gio.FILE_COPY_OVERWRITE is not specified and the target exists, then the error + gio.ERROR_EXISTS is returned. + </para> + <para> + If trying to overwrite a file over a directory the gio.ERROR_IS_DIRECTORY error is returned. + If trying to overwrite a directory with a directory the gio.ERROR_WOULD_MERGE error is returned. + </para> + <para> + If the source is a directory and the target does not exist, or gio.FILE_COPY_OVERWRITE is specified + and the target is a file, then the gio.ERROR_WOULD_RECURSE error may be returned + (if the native move operation isn't available). + </para> + </refsect2> + + <refsect2 id="method-giofile--query-default-handler"> + <title>gio.File.query_default_handler</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_default_handler</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> + if the handle was found, <literal>None</literal> if there were errors. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_default_handler</methodname>() method returns the + <link linkend="class-gioappinfo"><classname>gio.AppInfo</classname></link> that + is registered as the default application to handle the file specified by file. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be + cancelled by triggering the cancellable object from another thread. If the + operation was cancelled, the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-exists"> + <title>gio.File.query_exists</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_exists</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the file exists (and can be detected + without error), <literal>False</literal> otherwise (or if cancelled). + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_exists</methodname>() method is an tility function to check + if a particular file exists. This is implemented using + <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>() + and as such does blocking I/O. + </para> + <para> + Note that in many cases it is racy to first check for file existence and then execute + something based on the outcome of that, because the file might have been created or + removed in between the operations. The general approach to handling that is to not check, + but just do the operation and handle the errors as they come. + </para> + <para> + As an example of race-free checking, take the case of reading a file, and if it doesn't + exist, creating it. There are two racy versions: read it, and on error create it; and: + check if it exists, if not create it. These can both result in two processes creating the + file (with perhaps a partially written file as the result). The correct approach is to + always try to create the file with + <methodname><link linkend="method-giofile--create">gio.File.create</link></methodname>() + which will either atomically create the file or fail with a gio.ERROR_EXISTS error. + </para> + <para> + However, in many cases an existence check is useful in a user interface, for instance + to make a menu item sensitive/insensitive, so that you don't have to fool users that + something is possible and then just show and error dialog. If you do this, you should + make sure to also handle the errors that can happen due to races when you execute the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-file-type"> + <title>gio.File.query_file_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_file_type</methodname> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_MONITOR_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara> + a <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara> + <xref linkend="gio-file-type-constants" endterm="gio-file-type-constants-title"></xref> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_file_type</methodname>() method it's an utility function to inspect + the <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + of a file. This is implemented using + <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>() + and as such does blocking I/O. + </para> + <para> + The primary use case of this method is to check if a file is a regular file, directory, or symlink. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-filesystem-info"> + <title>gio.File.query_filesystem_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_filesystem_info</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attributes</parameter> :</term> + <listitem><simpara>an attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + or <literal>None</literal> if there was an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_filesystem_info</methodname>() method it's similar to + <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>(), + but obtains information about the filesystem the file is on, rather than the + file itself. For instance the amount of space available and the type of the filesystem. + </para> + <para> + The attribute value is a string that specifies the file attributes that should be gathered. + It is not an error if it's not possible to read a particular requested attribute from a file - + it just won't be set. attribute should be a comma-separated list of attribute or attribute + wildcards. The wildcard "*" means all attributes, and a wildcard like "fs:*" means all attributes + in the fs namespace. The standard namespace for filesystem attributes is "fs". Common attributes + of interest are gio.FILE_ATTRIBUTE_FILESYSTEM_SIZE (the total size of the filesystem in bytes), + gio.FILE_ATTRIBUTE_FILESYSTEM_FREE (number of bytes available), and gio.FILE_ATTRIBUTE_FILESYSTEM_TYPE + (type of the filesystem). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + <para> + If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. Other errors + are possible too, and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-filesystem-info-async"> + <title>gio.File.query_filesystem_info_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_filesystem_info_async</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attributes</parameter> :</term> + <listitem><simpara>an attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_filesystem_info_async</methodname>() method asynchronously + gets the requested information about the filesystem that the specified file is on. + The result is a GFileInfo object that contains key-value attributes + (such as type or size for the file). + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--query-filesystem-info">query_filesystem_info</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--query-filesystem-info-finish">gio.File.query_filesystem_info_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-filesystem-info-finish"> + <title>gio.File.query_filesystem_info_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_filesystem_info_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_filesystem_info_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--query-filesystem-info-async">gio.File.query_filesystem_info_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--query-info"> + <title>gio.File.query_filesystem_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attributes</parameter> :</term> + <listitem><simpara>an attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara> + a <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + for the given file or <literal>None</literal> if there was an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info</methodname>() method gets the requested + information about specified file. The result is a + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + object that contains key-value attributes (such as the type or size of the file). + </para> + <para> + The attribute value is a string that specifies the file attributes that should + be gathered. It is not an error if it's not possible to read a particular + requested attribute from a file - it just won't be set. attribute should be + a comma-separated list of attribute or attribute wildcards. The wildcard "*" + means all attributes, and a wildcard like "standard::*" means all attributes + in the standard namespace. An example attribute query be "standard::*,owner::user". + The standard attributes are available as defines, like gio.FILE_ATTRIBUTE_STANDARD_NAME. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + <para> + For symlinks, normally the information about the target of the symlink is returned, + rather than information about the symlink itself. However if you pass + gio.FILE_QUERY_INFO_NOFOLLOW_SYMLINKS in flags the information about + the symlink itself will be returned. Also, for symlinks that point to non-existing + files the information about the symlink itself will be returned. + </para> + <para> + If the file does not exist, the gio.ERROR_NOT_FOUND error will be + returned. Other errors are possible too, and depend on what kind of + filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-info-async"> + <title>gio.File.query_info_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_async</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attributes</parameter> :</term> + <listitem><simpara>an attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara> + a <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_async</methodname>() method asynchronously gets the + requested information about specified file. The result is a + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + object that contains key-value attributes (such as type or size for the file). + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--query-info">query_info</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--query-info-finish">gio.File.query_info_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-info-finish"> + <title>gio.File.query_info_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + for the given file or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--query-info-async">gio.File.query_info_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--query-settable-attributes"> + <title>gio.File.query_settable_attributes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_settable_attributes</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of + <link linkend="class-giofileattributeinfo"><classname>gio.FileAttributeInfo</classname></link> + describing the settable attributes. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_settable_attributes</methodname>() method obtain the + list of settable attributes for the file. + </para> + <para> + Returns the type and full attribute name of all the attributes that can be + set on this file. This doesn't mean setting it will always succeed though, + you might get an access failure, or some specific file may not support a specific attribute. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--query-writable-namespace"> + <title>gio.File.query_writable_namespace</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_writable_namespace</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of + <link linkend="class-giofileattributeinfo"><classname>gio.FileAttributeInfo</classname></link> + describing the writable namespaces. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_writable_namespace</methodname>() method obtain the + list of attribute namespaces where new attributes can be created by a user. + An example of this is extended attributes (in the "xattr" namespace). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--read"> + <title>gio.File.read</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read</methodname>() method opens a file for reading. The result + is a <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + that can be used to read the contents of the file. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + <para> + If the file does not exist, the gio.ERROR_NOT_FOUND error will be returned. + If the file is a directory, the gio.ERROR_IS_DIRECTORY error will be returned. + Other errors are possible too, and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--read-async"> + <title>gio.File.read_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_async</methodname>() method asynchronously opens file for reading. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--read">read</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--read-finish">gio.File.read_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--read-finish"> + <title>gio.File.read_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + file or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--read-async">gio.File.read_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--replace"> + <title>gio.File.replace</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace</methodname> + <methodparam><parameter role="keyword">etag</parameter></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>etag</parameter> :</term> + <listitem><simpara>an optional entity tag for the current + <link linkend="class-giofile"><classname>gio.File</classname></link>, + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace</methodname>() method returns an output stream for + overwriting the file, possibly creating a backup copy of the file first. + If the file doesn't exist, it will be created. + </para> + <para> + This will try to replace the file in the safest way possible so that any + errors during the writing will not affect an already existing copy of the file. + For instance, for local files it may write to a temporary file and then atomically + rename over the destination when the stream is closed. + </para> + <para> + By default files created are generally readable by everyone, but if you pass + gio.FILE_CREATE_PRIVATE in flags the file will be made readable only to + the current user, to the level that is supported on the target filesystem. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + <para> + If you pass in a non-<literal>None</literal> etag value, then this value is compared + to the current entity tag of the file, and if they differ an gio.ERROR_WRONG_ETAG error + is returned. This generally means that the file has been changed since you last read it. + You can get the new etag from + <methodname><link linkend="method-giofileoutputstream--get-etag">gio.FileOutputStream.get_etag</link></methodname>() + after you've finished writing and closed the GFileOutputStream. When you load a new file you can use + <methodname><link linkend="method-giofileinputstream--query-info">gio.FileInputStream.query_info</link></methodname>() + to get the etag of the file. + </para> + <para> + If make_backup is <literal>True</literal>, this function will attempt to make a backup + of the current file before overwriting it. If this fails a gio.ERROR_CANT_CREATE_BACKUP + error will be returned. If you want to replace anyway, try again + with make_backup set to <literal>False</literal>. + </para> + <para> + If the file is a directory the gio.ERROR_IS_DIRECTORY error will be returned, and + if the file is some other form of non-regular file then a gio.ERROR_NOT_REGULAR_FILE + error will be returned. Some file systems don't allow all file names, and may return an + gio.ERROR_INVALID_FILENAME error, and if the name is to long gio.ERROR_FILENAME_TOO_LONG + will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-async"> + <title>gio.File.replace_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>etag</parameter> :</term> + <listitem><simpara>an optional entity tag for the current + <link linkend="class-giofile"><classname>gio.File</classname></link>, + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_async</methodname>() method asynchronously overwrites the file, + replacing the contents, possibly creating a backup copy of the file first. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--replace">replace</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--replace-finish">gio.File.replace_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-contents"> + <title>gio.File.replace_contents</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_contents</methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>contents</parameter> :</term> + <listitem><simpara>a string containing the new contents for file. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>etag</parameter> :</term> + <listitem><simpara>the old entity tag for the document + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the new entity tag for the document. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_contents</methodname>() method replaces the contents + of file with contents of length bytes. If etag is specified (not NULL) any existing + file must have that etag, or the error gio.ERROR_WRONG_ETAG will be returned. + </para> + <para> + If make_backup is <literal>True</literal>, this function will attempt to make a backup of file. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + <para> + The returned etag can be used to verify that the file hasn't changed the next time it is saved over. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-contents-async"> + <title>gio.File.replace_contents_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_contents_async</methodname> + <methodparam><parameter role="keyword">contents</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">etag</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">make_backup</parameter><initializer>True</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_CREATE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>contents</parameter> :</term> + <listitem><simpara>a string containing the new contents for file. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>etag</parameter> :</term> + <listitem><simpara>an optional entity tag for the current + <link linkend="class-giofile"><classname>gio.File</classname></link>, + or <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>make_backup</parameter> :</term> + <listitem><simpara><literal>True</literal> if a backup should be created. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-create-flags-constants" endterm="gio-file-create-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_contents_async</methodname>() method starts an asynchronous + replacement of file with the given contents of length bytes. etag will + replace the document's current entity tag. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--replace-contents">replace_contents</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--replace-contents-finish">gio.File.replace_contents_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-contents-finish"> + <title>gio.File.replace_contents_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_contents_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the new entity tag for the document. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_contents_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--replace-contents-async">gio.File.replace_contents_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--replace-finish"> + <title>gio.File.replace_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>replace_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + or <literal>None</literal> if an error occurred. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>replace_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--replace-async">gio.File.replace_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--resolve-relative-path"> + <title>gio.File.resolve_relative_path</title> + + <programlisting><methodsynopsis language="python"> + <methodname>resolve_relative_path</methodname> + <methodparam><parameter role="keyword">relative_path</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">relative_path</parameter> :</term> + <listitem><simpara>a given relative path string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link> + to the resolved path. <literal>None</literal> if relative_path is <literal>None</literal> + or if file is invalid. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>resolve_relative_path</methodname>() method resolves a + relative path for file to an absolute path. + </para> + <para> + This call does no blocking i/o. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute"> + <title>gio.File.set_attribute</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">value_p</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>the type of the attribute . + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value_p</parameter> :</term> + <listitem><simpara>the value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute</methodname>() method sets an attribute in + the file with attribute name attribute to value. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute-byte-string"> + <title>gio.File.set_attribute_byte_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_byte_string</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a string containing the attribute's new value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_byte_string</methodname>() method Sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_BYTE_STRING to value. If attribute is of a different type, + this operation will fail, returning <literal>False</literal>. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute-int32"> + <title>gio.File.set_attribute_int32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_int32</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>an int containing the attribute's new value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_int32</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_INT32 to value. If attribute is of a different type, + this operation will fail. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute-int64"> + <title>gio.File.set_attribute_int64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_int64</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a long containing the attribute's new value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_int64</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_INT64 to value. If attribute is of a different type, + this operation will fail. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute-string"> + <title>gio.File.set_attribute_string</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_string</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a string containing the attribute's new value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_string</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_STRING to value. If attribute is of a different type, + this operation will fail. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute-uint32"> + <title>gio.File.set_attribute_uint32</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_uint32</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>an int containing the attribute's new value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_uint32</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_UINT32 to value. If attribute is of a different type, + this operation will fail. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attribute-uint64"> + <title>gio.File.set_attribute_uint64</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attribute_uint64</methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">value</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>attribute</parameter> :</term> + <listitem><simpara>a string containing the attribute's name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a long containing the attribute's new value. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attribute was set, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attribute_uint64</methodname>() method sets attribute of type + gio.FILE_ATTRIBUTE_TYPE_UINT64 to value. If attribute is of a different type, + this operation will fail. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by triggering + the cancellable object from another thread. If the operation was cancelled, the error + gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attributes-async"> + <title>gio.File.set_attributes_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attributes_async</methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>info</parameter> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attributes_async</methodname>() method asynchronously + sets the attributes of file with info. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--set-attributes-from-info">set_attributes_from_info</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--set-attributes-finish">gio.File.set_attributes_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attributes-finish"> + <title>gio.File.set_attributes_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attributes_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attributes were set correctly, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attributes_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--set-attributes-async">gio.File.set_attributes_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--set-attributes-from-info"> + <title>gio.File.set_attributes_from_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_attributes_from_info</methodname> + <methodparam><parameter role="keyword">info</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>info</parameter> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the attributes were set correctly, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_attributes_from_info</methodname>() method tries to set + all attributes in the GFileInfo on the target values, not stopping on the first error. + </para> + If there is any error during this operation then error will be set to the + first error. Error on particular fields are flagged by setting the "status" + field in the attribute value to gio.FILE_ATTRIBUTE_STATUS_ERROR_SETTING, + which means you can also detect further errors. + <para> + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-display-name"> + <title>gio.File.set_display_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_display_name</methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>display_name</parameter> :</term> + <listitem><simpara>a string conaining the name to display. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link> + specifying what file was renamed to, or <literal>None</literal> if there was an error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_display_name</methodname>() method renames file to + the specified display name. + </para> + <para> + The display name is converted from UTF8 to the correct encoding for the + target filesystem if possible and the file is renamed to this. + </para> + <para> + If you want to implement a rename operation in the user interface the + edit name (gio.FILE_ATTRIBUTE_STANDARD_EDIT_NAME) should be used as the + initial value in the rename widget, and then the result after editing + should be passed to + <methodname><link linkend="method-giofile--set-display-name">gio.File.set_dispay_name</link></methodname>(). + </para> + <para> + On success the resulting converted filename is returned. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-display-name-async"> + <title>gio.File.set_display_name_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_display_name_async</methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>display_name</parameter> :</term> + <listitem><simpara>a string conaining the name to display. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_display_name_async</methodname>() method asynchronously + sets the display name for a given GFile. + </para> + <para> + For more details, see + <methodname><link linkend="method-giofile--set-display-name">set_display_name</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--set-display-name-finish">gio.File.set_display_name_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--set-display-name-finish"> + <title>gio.File.set_display_name_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_display_name_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link> + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_display_name_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--set-display-name-async">gio.File.set_display_name_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofile--trash"> + <title>gio.File.trash</title> + + <programlisting><methodsynopsis language="python"> + <methodname>trash</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on successful trash, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>trash</methodname>() method sends file to the "Trashcan", if possible. + This is similar to deleting it, but the user can recover it before emptying the trashcan. + Not all file systems support trashing, so this call can return the gio.ERROR_NOT_SUPPORTED error. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofile--unmount-mountable"> + <title>gio.File.unmount_mountable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>unmount_mountable</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.FILE_QUERY_INFO_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-file-query-info-flags-constants" endterm="gio-file-query-info-flags-constants-title"></xref> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>unmount_mountable</methodname>() method unmounts a file of type gio.FILE_TYPE_MOUNTABLE. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giofile--unmount-mountable-finish">gio.File.unmount_mountable_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giofile--unmount-mountable-finish"> + <title>gio.File.unmount_mountable_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>unmount_mountable_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the operation finished successfully, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>unmount_mountable_finish</methodname>() method finishes an asynchronous + copy operation started with + <methodname><link linkend="method-giofile--unmount-mountable">gio.File.unmount_mountable</link></methodname>(). + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--file-parse-name"> + <title>gio.file_parse_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>file_parse_name</methodname> + <methodparam><parameter role="keyword">parse_name</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>parse_name</parameter> :</term> + <listitem><simpara>a file name or path to be parsed. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>parse_name</methodname>() function constructs a + <link linkend="class-giofile"><classname>gio.File</classname></link> + with the given parse_name (i.e. something given by g_file_get_parse_name()). + This operation never fails, but the returned object might not support any I/O + operation if the parse_name cannot be parsed. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-fileattributeinfo.xml b/docs/reference/pygio-fileattributeinfo.xml new file mode 100644 index 0000000..4b72c27 --- /dev/null +++ b/docs/reference/pygio-fileattributeinfo.xml @@ -0,0 +1,73 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofileattributeinfo"> + <refnamediv> + <refname>gio.FileAttributeInfo</refname> + <refpurpose>Information about a specific attribute.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileAttributeInfo</classname></ooclass> + <ooclass><classname>__builtin__.object</classname></ooclass> + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- __builtin__.object + +-- <link linkend="class-giofileattributeinfo">gio.FileAttributeInfo</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giofileattributeinfo"><classname>gio.FileAttributeInfo</classname></link> + contains information about a specific attribute. + </para> + </refsect1> + + <refsect1 id="attributes-giofileattributeinfo"> + <title>gio.FileAttributeInfo Attributes</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"name"</entry> + <entry>Read</entry> + <entry>The name of the attribute.</entry> + </row> + <row valign="top"> + <entry>"type"</entry> + <entry>Read</entry> + <entry>the + <xref linkend="gio-file-attribute-type-constants" endterm="gio-file-attribute-type-constants-title"></xref> + type of the attribute.</entry> + </row> + <row valign="top"> + <entry>"flags"</entry> + <entry>Read</entry> + <entry>a set of + <xref linkend="gio-file-attribute-flags-constants" endterm="gio-file-attribute-flags-constants-title"></xref>. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-fileenumerator.xml b/docs/reference/pygio-fileenumerator.xml new file mode 100644 index 0000000..4b16bf6 --- /dev/null +++ b/docs/reference/pygio-fileenumerator.xml @@ -0,0 +1,488 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofileenumerator"> + <refnamediv> + <refname>gio.FileEnumerator</refname> + <refpurpose>Enumerated Files Routines.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileEnumerator</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--close">close</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--close-async">close_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--close-finish">close_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--get-container">get_container</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--has-pending">has_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--is-closed">is_closed</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--next-file">next_file</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--next-files-async">next_files_async</link></methodname> + <methodparam><parameter role="keyword">num_files</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--next-files-finish">next_files_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileenumerator--set-pending">set_pending</link></methodname> + <methodparam><parameter role="keyword">pending</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giofileenumerator">gio.FileEnumerator</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giofileenumerator"> + <title>gio.FileEnumerator Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"container"</entry> + <entry>Write - Construct only</entry> + <entry>The container that is being enumerated.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + allows you to operate on a set of + <link linkend="class-giofile"><classname>gio.File</classname></link>s + returning a + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + structure for each file enumerated (e.g. + <methodname><link linkend="method-giofile--enumerate-children">gio.File.enumerate_children</link></methodname>() + will return a The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + for each of the children within a directory). + </para> + <para> + To get the next file's information from a + The <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> use + <methodname><link linkend="method-giofileenumerator--next-file">gio.FileEnumerator.next_file</link></methodname>() + or its asynchronous version, + <methodname><link linkend="method-giofileenumerator--next-files-async">gio.FileEnumerator.next_files_async</link></methodname>(). + Note that the asynchronous version will return a list of + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>s, + whereas the synchronous will only return the next file in the enumerator. + </para> + <para> + To close a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + use <methodname><link linkend="method-giofileenumerator--close">close</link></methodname>, + or its asynchronous version, + <methodname><link linkend="method-giofileenumerator--close-async">close_async</link></methodname>. + Once a <link linkend="class-giofileenumerator"><classname>gio.FileEnumerator</classname></link> + is closed, no further actions may be performed on it. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofileenumerator--close"> + <title>gio.FileEnumerator.close</title> + + <programlisting><methodsynopsis language="python"> + <methodname>close</methodname> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on success or + <literal>False</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>close</methodname>() method releases all resources used by this + enumerator, making the + <xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref> + return gio.ERROR_CLOSED on all calls. + </para> + <para> + This will be automatically called when the last reference is dropped, + but you might want to call this function to make sure resources are released + as early as possible. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--close-async"> + <title>gio.FileEnumerator.close_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>close_async</methodname> + <methodparam> + <parameter role="keyword">callback</parameter> + </methodparam> + <methodparam> + <parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">io_priority</parameter> :</term> + <listitem><simpara>The + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>close_async</methodname>() method asynchronously closes the file enumerator. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned in + <methodname><link linkend="method-giofileenumerator--close-finish">gio.FileEnumerator.close_finish</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--close-finish"> + <title>gio.FileEnumerator.close_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>close_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a GAsyncResult. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the close operation + has finished successfully.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>close_finish</methodname>() method finishes closing a file enumerator, started from + <methodname><link linkend="method-giofileenumerator--close-async">gio.FileEnumerator.close_async</link></methodname>(). + </para> + <para> + If the file enumerator was already closed when + <methodname><link linkend="method-giofileenumerator--close-async">gio.FileEnumerator.close_async</link></methodname>() + was called, then this function will report gio.ERROR_CLOSED in error, and return <literal>False</literal>. + If the file enumerator had pending operation when the close operation was started, then this function will report + gio.ERROR_PENDING, and return <literal>False</literal>. If cancellable was not <literal>None</literal>, then the operation + may have been cancelled by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be set, and <literal>False</literal> will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--get-container"> + <title>gio.FileEnumerator.get_container</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_container</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the <link linkend="class-giofile"><classname>gio.File</classname></link> + which is being enumerated. </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_container</methodname>() method gets the + <link linkend="class-giofile"><classname>gio.File</classname></link> + container which is being enumerated. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--has-pending"> + <title>gio.FileEnumerator.has_pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>has_pending</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the enumerator has pending operations.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>has_pending</methodname>() method checks if the file enumerator has pending operations. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--is-closed"> + <title>gio.FileEnumerator.is_closed</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_closed</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the enumerator is closed.</simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>is_closed</methodname>() method checks if the file enumerator has been closed. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--next-file"> + <title>gio.FileEnumerator.next_file</title> + + <programlisting><methodsynopsis language="python"> + <methodname>next_file</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + or <literal>None</literal> on error or end of enumerator. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>next_file</methodname>() method returns information for the next + file in the enumerated object. Will block until the information is available. + The <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + returned from this function will contain attributes that match the attribute string + that was passed when the GFileEnumerator was created. + </para> + <para> + On error, returns <literal>None</literal> and sets error to the error. If the enumerator + is at the end, <literal>None</literal> will be returned and error will be unset. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--next-files-async"> + <title>gio.FileEnumerator.next_files_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>next_files_async</methodname> + <methodparam><parameter role="keyword">num_files</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam> + <parameter role="keyword">io_priority</parameter><initializer><literal>glib.PRIORITY_DEFAULT</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">num_files</parameter> :</term> + <listitem><simpara>The number of file info objects to request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">io_priority</parameter> :</term> + <listitem><simpara>The + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>next_files_async</methodname>() method requests information for a number + of files from the enumerator asynchronously. When all i/o for the operation is finished + the callback will be called with the requested information. + </para> + <para> + The callback can be called with less than num_files files in case of error or at the + end of the enumerator. In case of a partial error the callback will be called with any + succeeding items and no error, and on the next request the error will be reported. If a + request is cancelled the callback will be called with gio.ERROR_CANCELLED. + </para> + <para> + During an async request no other sync and async calls are allowed, and will result in gio.ERROR_PENDING errors. + </para> + <para> + Any outstanding i/o request with higher priority (lower numerical value) will be executed + before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT. + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--next-files-finish"> + <title>gio.FileEnumerator.next_files_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>next_files_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a GAsyncResult. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list of + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>s. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>next_files_finish</methodname>() method finishes the + asynchronous operation started with + <methodname><link linkend="method-giofileenumerator--next-files-async">gio.FileEnumerator.next_files_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giofileenumerator--set-pending"> + <title>gio.FileEnumerator.set_pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_pending</methodname> + <methodparam><parameter role="keyword">pending</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">pending</parameter> :</term> + <listitem><simpara>A boolean value. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>push_current</methodname>() method sets the file enumerator as having pending operations. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-fileicon.xml b/docs/reference/pygio-fileicon.xml new file mode 100644 index 0000000..d4a443b --- /dev/null +++ b/docs/reference/pygio-fileicon.xml @@ -0,0 +1,109 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofileicon"> + <refnamediv> + <refname>gio.FileIcon</refname> + <refpurpose>Icons pointing to an image file.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileIcon</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + <ooclass><classname><link linkend="class-gioicon">gio.Icon</link></classname></ooclass> + <ooclass><classname><link linkend="class-gioloadableicon">gio.LoadableIcon</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giofileicon">gio.FileIcon</link></methodname> + <methodparam><parameter role="keyword">file</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileicon--get-file">get_file</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giofileicon">gio.FileIcon</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link> + specifies an icon by pointing to an image file to be used as icon. + </para> + </refsect1> + + <refsect1 id="constructor-giofileicon"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.FileIcon</methodname> + <methodparam><parameter role="keyword">file</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>file</parameter> :</term> + <listitem><simpara>a + <link linkend="class-giofile"><classname>gio.File</classname></link> + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link> + for the given file, or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new icon for a file. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofileicon--get-file"> + <title>gio.FileIcon.get_file</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_file</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <link linkend="class-giofile"><classname>gio.File</classname></link> + or <literal>None</literal>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_file</methodname>() method gets the + <link linkend="class-giofile"><classname>gio.File</classname></link> + associated with the given icon. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-fileinfo.xml b/docs/reference/pygio-fileinfo.xml new file mode 100644 index 0000000..33eeae7 --- /dev/null +++ b/docs/reference/pygio-fileinfo.xml @@ -0,0 +1,346 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofileinfo"> + <refnamediv> + <refname>gio.FileInfo</refname> + <refpurpose>File Information and Attributes</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileInfo</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giofileinfo">gio.FileInfo</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--clear-status">clear_status</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--copy-into">copy_into</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--dup">dup</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-as-string">get_attribute_as_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-boolean">get_attribute_boolean</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-byte-string">get_attribute_byte_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-data">get_attribute_data</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-int32">get_attribute_int32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-int64">get_attribute_int64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-object">get_attribute_object</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-status">get_attribute_status</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-string">get_attribute_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-type">get_attribute_type</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-uint32">get_attribute_uint32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-attribute-uint64">get_attribute_uint64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-content-type">get_content_type</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-display-name">get_display_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-edit-name">get_edit_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-etag">get_etag</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-file-type">get_file_type</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-is-backup">get_is_backup</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-is-hidden">get_is_hidden</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-is-symlink">get_is_symlink</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-modification-time">get_modification_time</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-name">get_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-size">get_size</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-sort-order">get_sort_order</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--get-symlink-target">get_symlink_target</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--has-attribute">has_attribute</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--list-attributes">list_attributes</link></methodname> + <methodparam><parameter role="keyword">name_space</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--remove-attribute">remove_attribute</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute">set_attribute</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">value_p</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-boolean">set_attribute_boolean</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-byte-string">set_attribute_byte_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-data">set_attribute_data</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-int32">set_attribute_int32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-int64">set_attribute_int64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-int64">set_attribute_mask</link></methodname> + <methodparam><parameter role="keyword">mask</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-object">set_attribute_object</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-status">set_attribute_status</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-string">set_attribute_string</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + <methodparam><parameter role="keyword">attr_value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-uint32">set_attribute_uint32</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-attribute-uint64">set_attribute_uint64</link></methodname> + <methodparam><parameter role="keyword">attribute</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-content-type">set_content_type</link></methodname> + <methodparam><parameter role="keyword">content_type</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-display-name">set_display_name</link></methodname> + <methodparam><parameter role="keyword">display_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-edit-name">set_edit_name</link></methodname> + <methodparam><parameter role="keyword">edit_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-file-type">set_file_type</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-icon">set_icon</link></methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-is-hidden">set_is_hidden</link></methodname> + <methodparam><parameter role="keyword">is_hidden</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-is-symlink">set_is_symlink</link></methodname> + <methodparam><parameter role="keyword">is_symlink</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-modification-time">set_modification_time</link></methodname> + <methodparam><parameter role="keyword">mtime</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-name">set_name</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-size">set_size</link></methodname> + <methodparam><parameter role="keyword">size</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-sort-order">set_sort_order</link></methodname> + <methodparam><parameter role="keyword">sort_order</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--set-symlink-tarset">set_symlink_tarset</link></methodname> + <methodparam><parameter role="keyword">symlink_target</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinfo--unset-attribute-mask">unset_attribute_mask</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giofileinfo">gio.FileInfo</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Functionality for manipulating basic metadata for files. + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + implements methods for getting information that all files should contain, + and allows for manipulation of extended attributes. + </para> + <para> + See <link linkend="class-giofileattribute"><classname>gio.FileAttribute</classname></link> + for more information on how GIO handles file attributes. + </para> + <para> + To obtain a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + for a <link linkend="class-giofile"><classname>gio.File</classname></link>, use + <methodname><link linkend="method-giofile--query-info">gio.File.query_info</link></methodname>() + (or its async variant). To obtain a + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + for a file input or output stream, use + <methodname><link linkend="method-giofileinputstream--query-info">gio.FileInputStream.query_info</link></methodname>() or + <methodname><link linkend="method-giofileoutputstream--query-info">gio.FileOutputStream.query_info</link></methodname>() + (or their async variants). + </para> + <para> + To change the actual attributes of a file, you should then set the attribute in the + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> and call + <methodname><link linkend="method-giofile--set-attributes-from-info">gio.File.set_attributes_from_info</link></methodname>() or + <methodname><link linkend="method-giofile--set-attributes-async">gio.File.set_attributes_async</link></methodname>() + on a <link linkend="class-giofile"><classname>gio.File</classname></link>. + </para> + <para> + However, not all attributes can be changed in the file. For instance, the + actual size of a file cannot be changed via + <methodname><link linkend="method-giofileinfo--set-size">gio.FileInfo.set_size</link></methodname>(). You may call + <methodname><link linkend="method-giofile--query-settable-attributes">gio.File.query_settable_attributes</link></methodname>() and + <methodname><link linkend="method-giofile--query-writable-namespace">gio.File.query_writable_namespace</link></methodname>() + to discover the settable attributes of a particular file at runtime. + </para> + <para> + <link linkend="class-giofileattributematcher"><classname>gio.FileAttributeMatcher</classname></link> + allows for searching through a GFileInfo for attributes. + </para> + </refsect1> + + <refsect1 id="constructor-giofileinfo"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.FileInfo</methodname> + <methodparam></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link> + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + <para> Unfinished section, you may want to see the relevant C API docs for methods descriptions.</para> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-fileinputstream.xml b/docs/reference/pygio-fileinputstream.xml new file mode 100644 index 0000000..723dc64 --- /dev/null +++ b/docs/reference/pygio-fileinputstream.xml @@ -0,0 +1,214 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofileinputstream"> + <refnamediv> + <refname>gio.FileInputStream</refname> + <refpurpose>Base class for implementing streaming input</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileInputStream</classname></ooclass> + <ooclass><classname><link linkend="class-gioinputstream">gio.InputStream</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinputstream--query-info">query_info</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinputstream--query-info-async">query_info_async</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileinputstream--query-info-finish">query_info_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> + +-- <link linkend="class-giofileinputstream">gio.FileInputStream</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interfaces</title> + <para> + <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + implements + <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + provides input streams that take their content from a file. + </para> + <para> + <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + implements <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link>, + which allows the input stream to jump to arbitrary positions in the file, provided the filesystem + of the file allows it. In addition to the generic g_seekable_ API, + <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> + has its own API for seeking and positioning. To find the position of a file input stream, use + <methodname><link linkend="method-gioseekable--tell">gio.Seekable.tell</link></methodname>(). + To find out if a file input stream supports seeking, use + <methodname><link linkend="method-gioseekable--can_seek">gio.Seekable.can_seek</link></methodname>(). + To position a file input stream, use + <methodname><link linkend="method-gioseekable--seek">gio.Seekable.seek</link></methodname>(). + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofileinputstream--query-info"> + <title>gio.FileInputStream.query_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">attributes</parameter> :</term> + <listitem><simpara>a file attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>, + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info</methodname>() method queries a file input stream + the given attributes. This function blocks while querying the stream. + For the asynchronous (non-blocking) version of this function, see + <methodname><link linkend="method-giofileinputstream--query-info-async">gio.FileInputStream.query_info_async</link></methodname>(). + While the stream is blocked, the stream will set the pending flag internally, + and any other operations on the stream will fail with gio.ERROR_PENDING. + </para> + </refsect2> + + <refsect2 id="method-giofileinputstream--query-info-async"> + <title>gio.FileInputStream.query_info_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_async</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">attributes</parameter> :</term> + <listitem><simpara>a file attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_async</methodname>() method queries the stream + information asynchronously. When the operation is finished callback will be + called. You can then call + <methodname><link linkend="method-giofileinputstream--query-info-finish">gio.FileInputStream.query_info_finish</link></methodname>() + to get the result of the operation. + </para> + <para> + For the synchronous version of this function, see + <methodname><link linkend="method-giofileinputstream--query-info">gio.FileInputStream.query_info</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was + cancelled, the error gio.ERROR_CANCELLED will be set + </para> + </refsect2> + + <refsect2 id="method-giofileinputstream--query-info-finish"> + <title>gio.FileInputStream.query_info_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>, + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giofileinputstream--query-info-async">gio.FileInputStream.query_info_async</link></methodname>(). + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-filemonitor.xml b/docs/reference/pygio-filemonitor.xml new file mode 100644 index 0000000..ef9ca33 --- /dev/null +++ b/docs/reference/pygio-filemonitor.xml @@ -0,0 +1,128 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofilemonitor"> + <refnamediv> + <refname>gio.FileMonitor</refname> + <refpurpose>File Monitor</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileMonitor</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilemonitor--cancel">cancel</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilemonitor--emit-event">emit_event</link></methodname> + <methodparam><parameter role="keyword">child</parameter></methodparam> + <methodparam><parameter role="keyword">other_file</parameter></methodparam> + <methodparam><parameter role="keyword">event_type</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilemonitor--is-cancelled">is_cancelled</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilemonitor--set-rate-limit">set_rate_limit</link></methodname> + <methodparam><parameter role="keyword">limit_msecs</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giofilemonitor">gio.FileMonitor</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giofilemonitor"> + <title>gio.FileMonitor Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"cancelled"</entry> + <entry>Read</entry> + <entry> + Whether the monitor has been cancelled. Default value: <literal>False</literal>. + </entry> + </row> + <row valign="top"> + <entry>"rate-limit"</entry> + <entry>Read/Write</entry> + <entry> + The limit of the monitor to watch for changes, in milliseconds. + Allowed values: >= 0. Default value: 800. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1 id="signal-prototypes-giofilemonitor"> + <title>gio.FileMonitor Signal Prototypes</title> + + <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> + + <variablelist> + <varlistentry> + <term><link linkend="signal-giofilemonitor--aborted">"changed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>filemonitor</parameter></methodparam> + <methodparam><parameter>file</parameter></methodparam> + <methodparam><parameter>other_file</parameter></methodparam> + <methodparam><parameter>event_type</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link> + monitors a file or directory for changes. + </para> + <para> + To obtain a <link linkend="class-giofilemonitor"><classname>gio.FileMonitor</classname></link> + for a file or directory, use + <methodname><link linkend="method-giofile--monitor">gio.FileMonitor.monitor</link></methodname>(), + <methodname><link linkend="method-giofile--monitor-file">gio.FileMonitor.monitor_file</link></methodname>(), or + <methodname><link linkend="method-giofile--monitor-directory">gio.FileMonitor.monitor_directory</link></methodname>(). + </para> + <para> + To get informed about changes to the file or directory you are monitoring, + connect to the "changed" signal. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + <para> Unfinished section, you may want to see the relevant C API docs for methods descriptions.</para> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-fileoutputstream.xml b/docs/reference/pygio-fileoutputstream.xml new file mode 100644 index 0000000..f4367d7 --- /dev/null +++ b/docs/reference/pygio-fileoutputstream.xml @@ -0,0 +1,257 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofileoutputstream"> + <refnamediv> + <refname>gio.FileOutputStream</refname> + <refpurpose>Base class for implementing streaming input</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FileOutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giooutputstream">gio.OutputStream</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileoutputstream--get-etag">get_etag</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileoutputstream--query-info">query_info</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileoutputstream--query-info-async">query_info_async</link></methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofileoutputstream--query-info-finish">query_info_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> + +-- <link linkend="class-giofileoutputstream">gio.FileOutputStream</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interfaces</title> + <para> + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + implements + <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + provides output streams that write their content to a file. + </para> + <para> + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + implements <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link>, + which allows the output stream to jump to arbitrary positions in the file and to truncate + the file, provided the filesystem of the file supports these operations. In addition to the + generic gio.Seekable. API, + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link> + has its own API for seeking and positioning. To find the position of a file output stream, use + <methodname><link linkend="method-gioseekable--tell">gio.Seekable.tell</link></methodname>(). + To find out if a file output stream supports seeking, use + <methodname><link linkend="method-gioseekable--can_seek">gio.Seekable.can_seek</link></methodname>(). + To position a file output stream, use + <methodname><link linkend="method-gioseekable--seek">gio.Seekable.seek</link></methodname>(). + To find out if a file output stream supports truncating, use + <methodname><link linkend="method-gioseekable--can_truncate">gio.FileOutputStream.can_truncate</link></methodname>(). + To truncate a file output stream, use + <methodname><link linkend="method-gioseekable--truncate">gio.Seekable.truncate</link></methodname>(). + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofileoutputstream--get-etag"> + <title>gio.FileOutputStream.get_etag</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_etag</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the entity tag for the stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_etag</methodname>() method gets the entity tag + for the file when it has been written. This must be called after the + stream has been written and closed, as the etag can change while writing. + </para> + </refsect2> + + <refsect2 id="method-giofileoutputstream--query-info"> + <title>gio.FileOutputStream.query_info</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">attributes</parameter> :</term> + <listitem><simpara>a file attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>, + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info</methodname>() method queries a file input stream + the given attributes. This function blocks while querying the stream. + For the asynchronous (non-blocking) version of this function, see + <methodname><link linkend="method-giofileoutputstream--query-info-async">gio.FileOutputStream.query_info_async</link></methodname>(). + While the stream is blocked, the stream will set the pending flag internally, + and any other operations on the stream will fail with gio.ERROR_PENDING. + </para> + <para> + Can fail if the stream was already closed (with error being set to gio.ERROR_CLOSED), + the stream has pending operations (with error being set to gio.ERROR_PENDING), or + if querying info is not supported for the stream's interface (with error being set to + gio.ERROR_NOT_SUPPORTED). In all cases of failure, NULL will be returned. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be set, and <literal>None</literal> will be returned. + </para> + </refsect2> + + <refsect2 id="method-giofileoutputstream--query-info-async"> + <title>gio.FileOutputStream.query_info_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_async</methodname> + <methodparam><parameter role="keyword">attributes</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">attributes</parameter> :</term> + <listitem><simpara>a file attribute query string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_async</methodname>() method queries the stream + information asynchronously. When the operation is finished callback will be + called. You can then call + <methodname><link linkend="method-giofileoutputstream--query-info-finish">gio.FileOutputStream.query_info_finish</link></methodname>() + to get the result of the operation. + </para> + <para> + For the synchronous version of this function, see + <methodname><link linkend="method-giofileoutputstream--query-info">gio.FileOutputStream.query_info</link></methodname>(). + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was + cancelled, the error gio.ERROR_CANCELLED will be set + </para> + </refsect2> + + <refsect2 id="method-giofileoutputstream--query-info-finish"> + <title>gio.FileOutputStream.query_info_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>query_info_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofileinfo"><classname>gio.FileInfo</classname></link>, + or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>query_info_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-giofileoutputstream--query-info-async">gio.FileOutputStream.query_info_async</link></methodname>(). + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-filterinputstream.xml b/docs/reference/pygio-filterinputstream.xml new file mode 100644 index 0000000..e6fb90b --- /dev/null +++ b/docs/reference/pygio-filterinputstream.xml @@ -0,0 +1,152 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofilterinputstream"> + <refnamediv> + <refname>gio.FilterInputStream</refname> + <refpurpose>Filter Input Stream</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FilterInputStream</classname></ooclass> + <ooclass><classname><link linkend="class-gioinputstream">gio.InputStream</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilterinputstream--get-base-stream">get_base_stream</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilterinputstream--get-close-base-stream">get_close_base_stream</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilterinputstream--set-close-base-stream">set_close_base_stream</link></methodname> + <methodparam><parameter role="keyword">close_base</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> + +-- <link linkend="class-giofilterinputstream">gio.FilterInputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giofilterinputstream"> + <title>gio.FilterInputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"base-stream"</entry> + <entry>Read - Write - Construct only</entry> + <entry>The underlying base stream on which the io ops will be done.</entry> + </row> + <row valign="top"> + <entry>"close-base-stream"</entry> + <entry>Read - Write - Construct only</entry> + <entry>If the base stream should be closed when the filter stream is closed. + Default value: <literal>True</literal>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Filter Input Stream. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofilterinputstream--get-base-stream"> + <title>gio.FilterInputStream.get_base_stream</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_base_stream</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_base_stream</methodname>() method gets the base + stream for the filter stream. + </para> + </refsect2> + + <refsect2 id="method-giofilterinputstream--get-close-base-stream"> + <title>gio.FilterInputStream.get_close_base_stream</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_close_base_stream</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the base stream + will be closed. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_close_base_stream</methodname>() method returns + whether the base stream will be closed when stream is closed. + </para> + </refsect2> + + <refsect2 id="method-giofilterinputstream--set-close-base-stream"> + <title>gio.FilterInputStream.set_close_base_stream</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_close_base_stream</methodname> + <methodparam><parameter role="keyword">close_base</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">close_base</parameter> :</term> + <listitem><simpara><literal>True</literal> to close the base stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_close_base_stream</methodname>() method sets whether + the base stream will be closed when stream is closed. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-filteroutputstream.xml b/docs/reference/pygio-filteroutputstream.xml new file mode 100644 index 0000000..78feaa2 --- /dev/null +++ b/docs/reference/pygio-filteroutputstream.xml @@ -0,0 +1,152 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giofilteroutputstream"> + <refnamediv> + <refname>gio.FilterOutputStream</refname> + <refpurpose>Filter Output Stream</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.FilterOutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giooutputstream">gio.OutputStream</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilteroutputstream--get-base-stream">get_base_stream</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilteroutputstream--get-close-base-stream">get_close_base_stream</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giofilteroutputstream--set-close-base-stream">set_close_base_stream</link></methodname> + <methodparam><parameter role="keyword">close_base</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> + +-- <link linkend="class-giofilteroutputstream">gio.FilterOutputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giofilteroutputstream"> + <title>gio.FilterOutputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"base-stream"</entry> + <entry>Read - Write - Construct only</entry> + <entry>The underlying base stream on which the io ops will be done.</entry> + </row> + <row valign="top"> + <entry>"close-base-stream"</entry> + <entry>Read - Write - Construct only</entry> + <entry>If the base stream should be closed when the filter stream is closed. + Default value: <literal>True</literal>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Filter Output Stream. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giofilteroutputstream--get-base-stream"> + <title>gio.FilterOutputStream.get_base_stream</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_base_stream</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_base_stream</methodname>() method gets the base + stream for the filter stream. + </para> + </refsect2> + + <refsect2 id="method-giofilteroutputstream--get-close-base-stream"> + <title>gio.FilterOutputStream.get_close_base_stream</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_close_base_stream</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the base stream + will be closed. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_close_base_stream</methodname>() method returns + whether the base stream will be closed when stream is closed. + </para> + </refsect2> + + <refsect2 id="method-giofilteroutputstream--set-close-base-stream"> + <title>gio.FilterOutputStream.set_close_base_stream</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_close_base_stream</methodname> + <methodparam><parameter role="keyword">close_base</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">close_base</parameter> :</term> + <listitem><simpara><literal>True</literal> to close the base stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_close_base_stream</methodname>() method sets whether + the base stream will be closed when stream is closed. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-functions.xml b/docs/reference/pygio-functions.xml new file mode 100644 index 0000000..c690a2f --- /dev/null +++ b/docs/reference/pygio-functions.xml @@ -0,0 +1,395 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="gio-functions"> + <refnamediv> + <refname>gio Functions</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<programlisting><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-can-be-executable">gio.content_type_can_be_executable</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-equals">gio.content_type_equals</link></methodname> + <methodparam><parameter role="keyword">type1</parameter></methodparam> + <methodparam><parameter role="keyword">type2</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-from-mime-type">gio.content_type_from_mime_type</link></methodname> + <methodparam><parameter role="keyword">mime_type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-get-description">gio.content_type_get_description</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-get-icon">gio.content_type_get_icon</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-get-mime-type">gio.content_type_get_mime_type</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-guess">gio.content_type_guess</link></methodname> + <methodparam><parameter role="keyword">filename</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">want_uncertain</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-is-a">gio.content_type_is_a</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">supertype</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-type-is-unknown">gio.content_type_is_unknown</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--content-types-get-registered">gio.content_types_get_registered</link></methodname> + <methodparam></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--io-error-from-errno">gio.io_error_from_errno</link></methodname> + <methodparam><parameter role="keyword">err_no</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + These functions are part of the <literal>PyGObject</literal> gio module + but are not directly associated with a specific class + </para> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--content-type-can-be-executable"> + <title>gio.content_type_can_be_executable</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_can_be_executable</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the file type corresponds + to a type that can be executable, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_can_be_executable</methodname>() function checks + if a content type can be executable. Note that for instance things like text files + can be executables (i.e. scripts and batch files). + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-equals"> + <title>gio.content_type_equals</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_equals</methodname> + <methodparam><parameter role="keyword">type1</parameter></methodparam> + <methodparam><parameter role="keyword">type2</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type1</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type2</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the two strings are + identical or equivalent, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_equals</methodname>() function compares + two content types for equality. + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-from-mime-type"> + <title>gio.content_type_from_mime_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_from_mime_type</methodname> + <methodparam><parameter role="keyword">mime_type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mime_type</parameter> :</term> + <listitem><simpara>a mime type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The content type or <literal>None</literal> when does not know. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_from_mime_type</methodname>() function tries + to find a content type based on the mime type name. + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-get-description"> + <title>gio.content_type_get_description</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_get_description</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a short description of the content type type. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_get_description</methodname>() function + gets the human readable description of the content type. + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-get-icon"> + <title>gio.content_type_get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_get_icon</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + corresponding to the content type. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_get_icon</methodname>() function + gets the icon for a content type. + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-get-mime-type"> + <title>gio.content_type_get_mime_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_get_mime_type</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the registered mime-type for the given type, + or <literal>None</literal> if unknown. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_get_mime_type</methodname>() function + gets the mime-type for the content type. If one is registered + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-guess"> + <title>gio.content_type_guess</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_guess</methodname> + <methodparam><parameter role="keyword">filename</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter></methodparam> + <methodparam><parameter role="keyword">want_uncertain</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>filename</parameter> :</term> + <listitem><simpara>a string, or <literal>None</literal>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>data</parameter> :</term> + <listitem><simpara>a stream of data, or <literal>None</literal>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>want_uncertain</parameter> :</term> + <listitem><simpara>a flag indicating the certainty of the result. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string indicating a guessed content type for the given data. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_guess</methodname>() function guesses + the content type based on example data. If the function is uncertain, + result_uncertain will be set to <literal>True</literal>. Either filename + or data may be <literal>None</literal>, in which case the guess will be + based solely on the other argument. + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-is-a"> + <title>gio.content_type_is_a</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_is_a</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + <methodparam><parameter role="keyword">supertype</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>supertype</parameter> :</term> + <listitem><simpara>a string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if type is a kind of + supertype, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_is_a</methodname>() function determines + if type is a subset of supertype. + </para> + </refsect2> + + <refsect2 id="function-gio--content-type-is-unknown"> + <title>gio.content_type_is_unknown</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_type_is_unknown</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a content type string. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the type is the unknown type. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_type_is_unknown</methodname>() function checks if + the content type is the generic "unknown" type. On unix this is the + "application/octet-stream" mimetype, while on win32 it is "*". + </para> + </refsect2> + + <refsect2 id="function-gio--content-types-get-registered"> + <title>gio.content_types_get_registered</title> + + <programlisting><methodsynopsis language="python"> + <methodname>content_types_get_registered</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the registered content types. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>content_types_get_registered</methodname>() function + gets a list of strings containing all the registered content types + known to the system. + </para> + </refsect2> + + <refsect2 id="function-gio--io-error-from-errno"> + <title>gio.io_error_from_errno</title> + + <programlisting><methodsynopsis language="python"> + <methodname>io_error_from_errno</methodname> + <methodparam><parameter role="keyword">err_no</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>err_no</parameter> :</term> + <listitem><simpara>Error number. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <xref linkend="gio-error-constants" endterm="gio-error-constants-title"></xref> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>io_error_from_errno</methodname>() function converts + error codes into GIO error codes. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-icon.xml b/docs/reference/pygio-icon.xml new file mode 100644 index 0000000..5a32d28 --- /dev/null +++ b/docs/reference/pygio-icon.xml @@ -0,0 +1,217 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioicon"> + <refnamediv> + <refname>gio.Icon</refname> + <refpurpose>Interface for icons.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Icon</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <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> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioicon">gio.Icon</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Known Derived Interfaces</title> + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> is required by + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> is implemented by + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link>, + <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link>, + <link linkend="class-gioemblem"><classname>gio.Emblem</classname></link>, + <link linkend="class-gioemblemedicon"><classname>gio.EmblemedIcon</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + is a very minimal interface for icons. It provides functions for checking + the equality of two icons, hashing of icons and serializing an icon to and from strings. + </para> + <para> + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + does not provide the actual pixmap for the icon as this is out of GIO's + scope, however implementations of + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + may contain the name of an icon (see + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link>), + or the path to an icon (see + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link>). + </para> + <!-- + <para> + To obtain a hash of a <link linkend="class-gioicon"><classname>gio.Icon</classname></link>, see + <methodname><link linkend="method-gioicon- -hash">gio.Icon.hash</link></methodname>(). + </para> + --> + <para> + 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 + <methodname><link linkend="method-gioicon- -new-from-string">gio.Icon.new_from_string</link></methodname>(). + </para> + <para> + If your application or library provides one or more + <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="function-gioicon--new-from-string">gio.icon_new_from_string</link></methodname>(). + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioicon--equal"> + <title>gio.Icon.equal</title> + + <programlisting><methodsynopsis language="python"> + <methodname>equal</methodname> + <methodparam><parameter role="keyword">icon2</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>icon2</parameter> :</term> + <listitem><simpara>the second + <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + 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-inputstream.xml b/docs/reference/pygio-inputstream.xml new file mode 100644 index 0000000..1bef333 --- /dev/null +++ b/docs/reference/pygio-inputstream.xml @@ -0,0 +1,730 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioinputstream"> + <refnamediv> + <refname>gio.InputStream</refname> + <refpurpose>Base class for implementing streaming input</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.InputStream</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--clear-pending">clear_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--close">close</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--close-async">close_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--close-finish">close_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--has-pending">has_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--is-closed">is_closed</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--read">read</link></methodname> + <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--read-async">read_async</link></methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--read-finish">read_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--read-part">read_part</link></methodname> + <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--set-pending">set_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--skip">skip</link></methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--skip-async">skip_async</link></methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioinputstream--skip-finish">skip_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + has functions to read from a stream ( + <methodname><link linkend="method-gioinputstream--read">gio.InputStream.read</link></methodname>() + ), to close a stream ( + <methodname><link linkend="method-gioinputstream--close">gio.InputStream.close</link></methodname>() + ) and to skip some content ( + <methodname><link linkend="method-gioinputstream--skip">gio.InputStream.skip</link></methodname>() + ). + </para> + <para> + To copy the content of an input stream to an output stream without manually + handling the reads and writes, use + <methodname><link linkend="method-giooutputstream--skip">gio.OutputStream.splice</link></methodname>(). + </para> + <para> + All of these functions have async variants too. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioinputstream--clear-pending"> + <title>gio.InputStream.clear_pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>clear_pending</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>clear_pending</methodname>() method clears the pending flag on stream. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--close"> + <title>gio.InputStream.close</title> + + <programlisting><methodsynopsis language="python"> + <methodname>close</methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on success + <literal>False</literal> on failure. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>close</methodname>() method closes the stream, releasing + resources related to it. + </para> + <para> + Once the stream is closed, all other operations will return gio.ERROR_CLOSED. + Closing a stream multiple times will not return an error. + </para> + <para> + Streams will be automatically closed when the last reference is dropped, but + you might want to call this function to make sure resources are released as + early as possible. + </para> + <para> + Some streams might keep the backing store of the stream (e.g. a file descriptor) + open after the stream is closed. See the documentation for the individual + stream for details. + </para> + <para> + On failure the first error that happened will be reported, but the close operation + will finish as much as possible. A stream that failed to close will still return + gio.ERROR_CLOSED for all operations. Still, it is important to check and report + the error to the user. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--close-async"> + <title>gio.InputStream.close_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>close_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>close_async</methodname>() method asynchronously requests an + asynchronous closes of the stream, releasing resources related to it. + </para> + <para> + For more details, see + <methodname><link linkend="method-gioinputstream--close">gio.InputStream.close</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-gioinputstream--close-finish">gio.InputStream.close_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--close-finish"> + <title>gio.InputStream.close_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>close_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the stream was closed successfully. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>close_finish</methodname>() method finishes an asynchronous + file append operation started with + <methodname><link linkend="method-gioinputstream--close-async">gio.InputStream.close_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--has-pending"> + <title>gio.InputStream.has_pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>has_pending</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if stream has pending actions. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>has_pending</methodname>() method checks if an input stream has pending actions. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--is-closed"> + <title>gio.InputStream.is_closed</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_closed</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the stream is closed. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>is_closed</methodname>() method checks if an input stream is closed. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--read"> + <title>gio.InputStream.read</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read</methodname> + <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">count</parameter> :</term> + <listitem><simpara>optionally the number of bytes that will be read from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The number of bytes read, or -1 on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read</methodname>() method tries to read count bytes from + the stream into the buffer starting at buffer. Will block during this read. + </para> + <para> + This function is similar to + <methodname><link linkend="method-gioinputstream--read-part">gio.InputStream.read_part</link></methodname>(), + except it tries to read as many bytes as requested, only stopping on an error or end of stream. + </para> + <para> + On a successful read of count bytes, or if we reached the end of the stream, + <literal>True</literal> is returned, and bytes_read is set to the number of bytes read into buffer. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + </para> + <para> + If there is an error during the operation <literal>False</literal> is returned and error + is set to indicate the error status, bytes_read is updated to contain the number of + bytes read into buffer before the error occurred. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--read-async"> + <title>gio.InputStream.read_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_async</methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>count</parameter> :</term> + <listitem><simpara>the number of bytes that will be read from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_async</methodname>() method requests an asynchronous read + of count bytes from the stream into the buffer. + </para> + <para> + For more details, see + <methodname><link linkend="method-gioinputstream--read">gio.InputStream.read</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-gioinputstream--read-finish">gio.InputStream.read_finish</link></methodname>() + to get the result of the operation. + </para> + <para> + During an async request no other sync and async calls are allowed, and + will result in gio.ERROR_PENDING errors. + </para> + <para> + A value of count larger than G_MAXSSIZE will cause a gio.ERROR_INVALID_ARGUMENT error. + </para> + <para> + On success, the number of bytes read into the buffer will be passed to the callback. + It is not an error if this is not the same as the requested size, as it can happen e.g. + near the end of a file, but generally we try to read as many bytes as requested. Zero + is returned on end of file (or if count is zero), but never otherwise. + </para> + <para> + Any outstanding i/o request with higher priority (lower numerical value) will be + executed before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT. + </para> + <para> + The asyncronous methods have a default fallback that uses threads to implement asynchronicity, so + they are optional for inheriting classes. However, if you override one you must override all. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--read-finish"> + <title>gio.InputStream.read_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The number of bytes read in, or -1 on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_finish</methodname>() method finishes an asynchronous + stream read operation started by + <methodname><link linkend="method-gioinputstream--read-async">gio.InputStream.read_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--read-part"> + <title>gio.InputStream.read_part</title> + + <programlisting><methodsynopsis language="python"> + <methodname>read_part</methodname> + <methodparam><parameter role="keyword">count</parameter><initializer>-1</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">count</parameter> :</term> + <listitem><simpara>optionally the number of bytes that will be read from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The number of bytes read, or -1 on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>read_part</methodname>() method tries to read count bytes from + the stream into the buffer starting at buffer. Will block during this read. + </para> + <para> + If count is zero returns zero and does nothing. A value of count larger than + G_MAXSSIZE will cause a gio.ERROR_INVALID_ARGUMENT error. + </para> + <para> + On success, the number of bytes read into the buffer is returned. It is + not an error if this is not the same as the requested size, as it can + happen e.g. near the end of a file. Zero is returned on end of file + (or if count is zero), but never otherwise. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + </para> + <para> + On error -1 is returned and error is set accordingly. + </para> + <note> + This method roughly corresponds to C GIO g_input_stream_read. + </note> + </refsect2> + + <refsect2 id="method-gioinputstream--set-pending"> + <title>gio.InputStream.set_pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_pending</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if pending was previously + unset and is now set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_pending</methodname>() method sets stream to have actions pending. + If the pending flag is already set or stream is closed, + it will return <literal>False</literal> and set error. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--skip"> + <title>gio.InputStream.skip</title> + + <programlisting><methodsynopsis language="python"> + <methodname>skip</methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">count</parameter> :</term> + <listitem><simpara>the number of bytes that will be skipped from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The number of bytes skipped, or -1 on error + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>skip</methodname>() method tries to skip count bytes + from the stream. Will block during the operation. + </para> + <para> + This is identical to + <methodname><link linkend="method-gioinputstream--read">read</link></methodname>(), + from a behaviour standpoint, but the bytes that are skipped are not + returned to the user. Some streams have an implementation that is more + efficient than reading the data. + </para> + <para> + This function is optional for inherited classes, as the default implementation emulates it using read. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled by + triggering the cancellable object from another thskip. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. Cancelling a close will still leave + the stream closed, but some streams can use a faster close that doesn't block to e.g. + check errors. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--skip-async"> + <title>gio.InputStream.skip_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>skip_async</methodname> + <methodparam><parameter role="keyword">count</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>count</parameter> :</term> + <listitem><simpara>the number of bytes that will be skipped from the stream. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncskipyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>io_priority</parameter> :</term> + <listitem><simpara>the + <xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> + of the request. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>skip_async</methodname>() method request an asynchronous + skip of count bytes from the stream. + </para> + <para> + For more details, see + <methodname><link linkend="method-gioinputstream--skip">gio.InputStream.skip</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-gioinputstream--skip-finish">gio.InputStream.skip_finish</link></methodname>() + to get the result of the operation. + </para> + <para> + During an async request no other sync and async calls are allowed, and + will result in gio.ERROR_PENDING errors. + </para> + <para> + A value of count larger than G_MAXSSIZE will cause a gio.ERROR_INVALID_ARGUMENT error. + </para> + <para> + On success, the number of bytes skipped will be passed to the callback. It is + not an error if this is not the same as the requested size, as it can happen + e.g. near the end of a file, but generally we try to skip as many bytes as requested. + Zero is returned on end of file (or if count is zero), but never otherwise. + </para> + <para> + Any outstanding i/o request with higher priority (lower numerical value) will be + executed before an outstanding request with lower priority. Default priority is glib.PRIORITY_DEFAULT. + </para> + <para> + The asyncronous methods have a default fallback that uses thskips to implement asynchronicity, so + they are optional for inheriting classes. However, if you override one you must override all. + </para> + </refsect2> + + <refsect2 id="method-gioinputstream--skip-finish"> + <title>gio.InputStream.skip_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>skip_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The number of bytes skipped in, or -1 on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>skip_finish</methodname>() method finishes an asynchronous + stream skip operation started by + <methodname><link linkend="method-gioinputstream--skip-async">gio.InputStream.skip_async</link></methodname>(). + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-loadableicon.xml b/docs/reference/pygio-loadableicon.xml new file mode 100644 index 0000000..93198c4 --- /dev/null +++ b/docs/reference/pygio-loadableicon.xml @@ -0,0 +1,198 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioloadableicon"> + <refnamediv> + <refname>gio.LoadableIcon</refname> + <refpurpose>Interface for icons.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.LoadableIcon</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioloadableicon--load">load</link></methodname> + <methodparam><parameter role="keyword">size</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioloadableicon--load-async">load_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">size</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-gioloadableicon--load-finish">load_finish</link></methodname> + <methodparam><parameter role="keyword">res</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioloadableicon">gio.LoadableIcon</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link> requires + <link linkend="class-gioicon"><classname>gio.Icon</classname></link>. and + <link linkend="class-gobject"><classname>gobject.GObject</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link> is implemented by + <link linkend="class-giofileicon"><classname>gio.FileIcon</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioloadableicon"><classname>gio.LoadableIcon</classname></link> + extends the <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + interface and adds the ability to load icons from streams. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioloadableicon--load"> + <title>gio.LoadableIcon.load</title> + + <programlisting><methodsynopsis language="python"> + <methodname>load</methodname> + <methodparam><parameter role="keyword">size</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>size</parameter> :</term> + <listitem><simpara>an integer + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 2 tuple containing a + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + to read the icon from and a string containing the icon type. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>load</methodname>() method loads a loadable icon. + For the asynchronous version of this function, see + <methodname><link linkend="method-gioloadableicon--load-async">gio.LoadableIcon.load_async</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-gioloadableicon--load-async"> + <title>gio.LoadableIcon.load_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>load_async</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">size</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>size</parameter> :</term> + <listitem><simpara>an integer + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>user_data</parameter> :</term> + <listitem><simpara>the data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>load_async</methodname>() method loads an icon asynchronously. + </para> + <para> + For more details, see + <methodname><link linkend="method-gioloadableicon--load">gio.LoadableIcon.load</link></methodname>() + which is the synchronous version of this call. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-gioloadableicon--load-finish">gio.LoadableIcon.load_finish</link></methodname>() + to get the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-gioloadableicon--load-finish"> + <title>gio.LoadableIcon.load_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>load_finish</methodname> + <methodparam><parameter role="keyword">res</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>res</parameter> :</term> + <listitem><simpara>a + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 2 tuple containing a + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + to read the icon from and a string containing the icon type. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>load_finish</methodname>() method finishes an asynchronous + icon load started in + <methodname><link linkend="method-gioloadableicon--load-async">gio.LoadableIcon.load_async</link></methodname>(). + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-memoryinputstream.xml b/docs/reference/pygio-memoryinputstream.xml new file mode 100644 index 0000000..7d8cffb --- /dev/null +++ b/docs/reference/pygio-memoryinputstream.xml @@ -0,0 +1,151 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giomemoryinputstream"> + <refnamediv> + <refname>gio.MemoryInputStream</refname> + <refpurpose>Base class for implementing streaming input</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.MemoryInputStream</classname></ooclass> + <ooclass><classname><link linkend="class-gioinputstream">gio.InputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giomemoryinputstream">gio.MemoryInputStream</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + + <methodsynopsis language="python"> + <methodname><link linkend="method-giomemoryinputstream--add-data">add_data</link></methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> + +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--memory-input-stream-new-from-data">gio.memory_input_stream_new_from_data</link></methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> + +-- <link linkend="class-giomemoryinputstream">gio.MemoryInputStream</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interfaces</title> + <para> + <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link> + implements + <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link> + is a class for using arbitrary memory chunks as input for GIO streaming input operations. + </para> + </refsect1> + + <refsect1 id="constructor-giomemoryinputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.MemoryInputStream</methodname> + <methodparam><parameter role="keyword">icon</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates an empty + <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link>. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giomemoryinputstream--add-data"> + <title>gio.MemoryInputStream.add_data</title> + + <programlisting><methodsynopsis language="python"> + <methodname>add_data</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>input data. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>add_data</methodname>() method appends data to data + that can be read from the input stream + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--memory-input-stream-new-from-data"> + <title>gio.memory_input_stream_new_from_data</title> + + <programlisting><methodsynopsis language="python"> + <methodname>memory_input_stream_new_from_data</methodname> + <methodparam><parameter role="keyword">data</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>data</parameter> :</term> + <listitem><simpara>input data. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A new + <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link> + read from data + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>memory_input_stream_new_from_data</methodname>() function creates + a new <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link> + with data in memory. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-memoryoutputstream.xml b/docs/reference/pygio-memoryoutputstream.xml new file mode 100644 index 0000000..f044496 --- /dev/null +++ b/docs/reference/pygio-memoryoutputstream.xml @@ -0,0 +1,175 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giomemoryoutputstream"> + <refnamediv> + <refname>gio.MemoryOutputStream</refname> + <refpurpose>Streaming output operations on memory chunks</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.MemoryOutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giooutputstream">gio.OutputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giomemoryoutputstream">gio.MemoryOutputStream</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + + <methodsynopsis language="python"> + <methodname><link linkend="method-giomemoryoutputstream--get-contents">get_contents</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomemoryoutputstream--get-data-size">get_data_size</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomemoryoutputstream--get-size">get_size</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> + +-- <link linkend="class-giomemoryoutputstream">gio.MemoryOutputStream</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interfaces</title> + <para> + <link linkend="class-giomemoryoutputstream"><classname>gio.MemoryOutputStream</classname></link> + implements + <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giomemoryoutputstream"><classname>gio.MemoryOutputStream</classname></link> + is a class for using arbitrary memory chunks as output for GIO streaming output operations. + </para> + </refsect1> + + <refsect1 id="constructor-giomemoryoutputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.MemoryOutputStream</methodname> + <methodparam></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giomemoryoutputstream"><classname>gio.MemoryOutputStream</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new + <link linkend="class-giomemoryoutputstream"><classname>gio.MemoryOutputStream</classname></link>. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giomemoryoutputstream--get-contents"> + <title>gio.MemoryOutputStream.get_contents</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_contents</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the stream's data + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_contents</methodname>() method gets any loaded data + from the ostream. + </para> + <para> + Note that the returned data may become invalid on the next write or truncate + operation on the stream. + </para> + </refsect2> + + <refsect2 id="method-giomemoryoutputstream--get-data-size"> + <title>gio.MemoryOutputStream.get_data_size</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_data_size</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the number of bytes written to the stream + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_data_size</methodname>() method returns the number + of bytes from the start up to including the last byte written in the + stream that has not been truncated away. + </para> + </refsect2> + + <refsect2 id="method-giomemoryoutputstream--get-size"> + <title>gio.MemoryOutputStream.get_size</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_size</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the number of bytes allocated for the data buffer + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_size</methodname>() method gets the size of the + currently allocated data area (availible from + <methodname><link linkend="method-giomemoryoutputstream--get-contents">gio.MemoryOutputStream.get_contents</link></methodname>() + ). + </para> + <para> + Note that for growable streams the returned size may become invalid on the next write or truncate operation on the stream. + </para> + <para> + If you want the number of bytes currently written to the stream, use + <methodname><link linkend="method-giomemoryoutputstream--get-data-size">gio.MemoryOutputStream.get_data_size</link></methodname>(). + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-mount.xml b/docs/reference/pygio-mount.xml new file mode 100644 index 0000000..aa635d4 --- /dev/null +++ b/docs/reference/pygio-mount.xml @@ -0,0 +1,961 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giomount"> + <refnamediv> + <refname>gio.Mount</refname> + <refpurpose>Mount management</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Mount</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--can-eject">can_eject</link></methodname> + <methodparam></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="method-giomount--can-unmount">can_unmount</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--eject">eject</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--eject-finish">eject_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--get-drive">get_drive</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--get-name">get_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--get-root">get_root</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--get-uuid">get_uuid</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--get-volume">get_volume</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--guess-content-type">guess_content_type</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">force_rescan</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--guess-content-type-finish">guess_content_type_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--guess-content-type-sync">guess_content_type_sync</link></methodname> + <methodparam><parameter role="keyword">force_rescan</parameter></methodparam> + <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> + <methodparam><parameter role="keyword">mount_operation</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomount--remount-finish">remount_finish</link></methodname> + <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> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <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> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-giomount">gio.Mount</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-giomount"><classname>gio.Mount</classname></link> requires + <link linkend="class-gobject"><classname>gobject.GObject</classname></link> + </para> + </refsect1> + + <refsect1 id="signal-prototypes-giomount"> + <title>gio.Mount Signal Prototypes</title> + + <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> + + <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> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomount--unmounted">"unmounted"</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> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giomount"><classname>gio.Mount</classname></link> + interface represents user-visible mounts. Note, when porting from GnomeVFS, + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + is the moral equivalent of GnomeVFSVolume. + + </para> + <para> + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + is a "mounted" filesystem that you can access. Mounted is in quotes because + it's not the same as a unix mount, it might be a gvfs mount, but you can still + access the files on it if you use GIO. Might or might not be related to a volume object. + </para> + <para> + Unmounting a GMount instance is an asynchronous operation. For more information + about asynchronous operations, see GAsyncReady and GSimpleAsyncReady. To unmount + a <link linkend="class-giomount"><classname>gio.Mount</classname></link> instance, + first call + g_mount_unmount() + with (at least) the GMount instance and a GAsyncReadyCallback. The callback will + be fired when the operation has resolved (either with success or failure), and a + GAsyncReady structure will be passed to the callback. That callback should then call + g_mount_unmount_finish() + with the GMount and the GAsyncReady data to see if the operation was completed successfully. + If an error is present when g_mount_unmount_finish() is called, then it will be filled + with any error information. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giomount--can-eject"> + <title>gio.Mount.can_eject</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_eject</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the mount can be ejected, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_eject</methodname>() method checks if a mount can be ejected. + </para> + </refsect2> + + <refsect2 id="method-giomount--can-unmount"> + <title>gio.Mount.can_unmount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_unmount</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the mount can be unmounted, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_eject</methodname>() method checks if a mount can be unmounted. + </para> + </refsect2> + + <refsect2 id="method-giomount--eject"> + <title>gio.Mount.eject</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags affecting the unmount if required for eject + <xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject</methodname>() method asynchronously ejects a mount. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giomount--eject-finish">gio.Mount.eject_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giomount--eject-finish"> + <title>gio.Mount.eject_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the mount has been ejected + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject_finish</methodname>() method finishes ejecting a mount. + </para> + </refsect2> + + <refsect2 id="method-giomount--get-drive"> + <title>gio.Mount.get_drive</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_drive</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><link linkend="class-giodrive"><classname>gio.Drive</classname></link> + or <literal>None</literal> if mount is not associated with a volume or a drive. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_drive</methodname>() method gets the drive for the mount. + </para> + <para> + This is a convenience method for getting the + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + and then using that object to get the + <link linkend="class-giodrive"><classname>gio.Drive</classname></link>. + </para> + </refsect2> + + <refsect2 id="method-giomount--get-icon"> + <title>gio.Mount.get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_icon</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><link linkend="class-gioicon"><classname>gio.Icon</classname></link> + for the mount. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_icon</methodname>() method gets the icon for mount. + </para> + </refsect2> + + <refsect2 id="method-giomount--get-name"> + <title>gio.Mount.get_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the name for the given mount. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_name</methodname>() method gets the name of mount. + </para> + </refsect2> + + <refsect2 id="method-giomount--get-root"> + <title>gio.Mount.get_root</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_root</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giofile"><classname>gio.File</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_root</methodname>() method gets the root directory on mount. + </para> + </refsect2> + + <refsect2 id="method-giomount--get-uuid"> + <title>gio.Mount.get_uuid</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_uuid</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the UUID for mount or <literal>None</literal> + if no UUID can be computed. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_uuid</methodname>() method gets the UUID for the mount. + The reference is typically based on the file system UUID for the mount in + question and should be considered an opaque string. Returns <literal>None</literal> + if there is no UUID available + </para> + </refsect2> + + <refsect2 id="method-giomount--get-volume"> + <title>gio.Mount.get_volume</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_volume</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + or <literal>None</literal> if mount is not associated with a volume. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_volume</methodname>() method gets the volume for the mount. + </para> + </refsect2> + + <refsect2 id="method-giomount--guess-content-type"> + <title>gio.Mount.guess_content_type</title> + + <programlisting><methodsynopsis language="python"> + <methodname>guess_content_type</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">force_rescan</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">force_rescan</parameter> :</term> + <listitem><simpara>Whether to force a rescan of the content. Otherwise a cached result will be used if available. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>guess_content_type</methodname>() method asynchronously tries to guess the type of + content stored on mount. Returns one or more textual identifiers of well-known content + types (typically prefixed with "x-content/"), e.g. x-content/image-dcf for camera memory + cards. See the shared-mime-info specification for more on x-content types. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giomount--guess-content-type-finish">gio.Mount.guess_content_type_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giomount--guess-content-type-finish"> + <title>gio.Mount.guess_content_type_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>guess_content_type_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list of types or <literal>None</literal> on error. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>guess_content_type_finish</methodname>() method finishes guessing content + types of mount. If any errors occured during the operation, error will be set to + contain the errors and FALSE will be returned. In particular, you may get an + gio.ERROR_NOT_SUPPORTED if the mount does not support content guessing. + </para> + </refsect2> + + <refsect2 id="method-giomount--guess-content-type-sync"> + <title>gio.Mount.guess_content_type_sync</title> + + <programlisting><methodsynopsis language="python"> + <methodname>guess_content_type_sync</methodname> + <methodparam><parameter role="keyword">force_rescan</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">force_rescan</parameter> :</term> + <listitem><simpara>Whether to force a rescan of the content. Otherwise a cached result will be used if available. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>guess_content_type_sync</methodname>() method tries to guess + the type of content stored on mount. Returns one or more textual identifiers + of well-known content types (typically prefixed with "x-content/"), e.g. + x-content/image-dcf for camera memory cards. See the shared-mime-info specification + for more on x-content types. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + This is an synchronous operation and as such may block doing IO; see + <methodname><link linkend="method-giomount--guess-content-type">gio.Mount.guess_content_type</link></methodname>() + 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> + + <programlisting><methodsynopsis language="python"> + <methodname>remount</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">mount_operation</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags affecting the unmount if required for eject + <xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">mount_operation</parameter> :</term> + <listitem><simpara>a <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + or <literal>None</literal> to avoid user interaction. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>remount</methodname>() method asynchronously remounts a mount. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giomount--remount-finish">gio.Mount.remount_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giomount--remount-finish"> + <title>gio.Mount.remount_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>remount_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the mount has been remounted + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + 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> + + <programlisting><methodsynopsis language="python"> + <methodname>unmount</methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags affecting the unmount if required for eject + <xref linkend="gio-mount-unmount-flags-constants" endterm="gio-mount-unmount-flags-constants-title"></xref>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>unmount</methodname>() method asynchronously unmounts a mount. + </para> + <para> + If cancellable is not <literal>None</literal>, then the operation can be cancelled + by triggering the cancellable object from another thread. If the operation was cancelled, + the error gio.ERROR_CANCELLED will be returned. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giomount--unmount-finish">gio.Mount.unmount_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giomount--unmount-finish"> + <title>gio.Mount.unmount_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>unmount_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the mount has been unmounted + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + 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> + + <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 when the mount has been changed. + </para> + </refsect2> + + <refsect2 id="signal-giomount--unmounted"> + <title>The "unmounted" 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> + This signal is emitted when the + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + have been unmounted. + </para> + </refsect2> + + </refsect1> +</refentry> diff --git a/docs/reference/pygio-mountoperation.xml b/docs/reference/pygio-mountoperation.xml new file mode 100644 index 0000000..34dec13 --- /dev/null +++ b/docs/reference/pygio-mountoperation.xml @@ -0,0 +1,726 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giomountoperation"> + <refnamediv> + <refname>gio.MountOperation</refname> + <refpurpose>Authentication methods for mountable locations.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.MountOperation</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giomountoperation">gio.MountOperation</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-anonymous">get_anonymous</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-choice">get_choice</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-domain">get_domain</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-password">get_password</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-password-save">get_password_save</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--get-username">get_username</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--reply">replay</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-anonymous">set_anonymous</link></methodname> + <methodparam><parameter role="keyword">anonymous</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-choice">set_choice</link></methodname> + <methodparam><parameter role="keyword">choice</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-domain">set_domain</link></methodname> + <methodparam><parameter role="keyword">domain</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-password">set_password</link></methodname> + <methodparam><parameter role="keyword">password</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-password-save">set_password_save</link></methodname> + <methodparam><parameter role="keyword">save</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giomountoperation--set-username">set_username</link></methodname> + <methodparam><parameter role="keyword">username</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giomountoperation">gio.MountOperation</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giomountoperation"> + <title>gio.MountOperation Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"anonymous"</entry> + <entry>Read/Write</entry> + <entry> + Whether to use an anonymous user when authenticating. + Default value: <literal>False</literal> + </entry> + </row> + <row valign="top"> + <entry>"choice"</entry> + <entry>Read/Write</entry> + <entry> + The index of the user's choice when a question is asked during + the mount operation. See the "ask-question" signal. + Allowed values: >= 0 Default value: 0 + </entry> + </row> + <row valign="top"> + <entry>"domain"</entry> + <entry>Read/Write</entry> + <entry> + The domain to use for the mount operation. Default value: <literal>None</literal> + </entry> + </row> + <row valign="top"> + <entry>"password"</entry> + <entry>Read/Write</entry> + <entry> + The password that is used for authentication when carrying out the + mount operation. Default value: <literal>None</literal> + </entry> + </row> + <row valign="top"> + <entry>"password-save"</entry> + <entry>Read/Write</entry> + <entry> + Determines if and how the password information should be saved. + Default value: gio.PASSWORD_SAVE_NEVER + </entry> + </row> + <row valign="top"> + <entry>"username"</entry> + <entry>Read/Write</entry> + <entry> + The user name that is used for authentication when carrying out the + mount operation. Default value: <literal>None</literal> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1 id="signal-prototypes-giomountoperation"> + <title>gio.MountOperation Signal Prototypes</title> + + <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> + + <variablelist> + <varlistentry> + <term><link linkend="signal-giomountoperation--aborted">"aborted"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomountoperation--ask-password">"ask-password"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>default_user</parameter></methodparam> + <methodparam><parameter>default_domain</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomountoperation--ask-question">"ask-question"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>choices</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giomountoperation--reply">"reply"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>result</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + provides a mechanism for authenticating mountable operations, such as loop mounting files, + hard drive partitions or server locations. + </para> + <para> + Mounting operations are handed a + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + that then can use if they require any privileges or authentication for their volumes to be + mounted (e.g. a hard disk partition or an encrypted filesystem), or if they are implementing + a remote server protocol which requires user credentials such as FTP or WebDAV. + </para> + <para> + Users should instantiate a subclass of this that implements all the various callbacks + to show the required dialogs, such as + <link linkend="class-gtkmountoperation"><classname>gtk.MountOperation</classname></link>. + </para> + </refsect1> + + <refsect1 id="constructor-giomountoperation"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.MountOperation</methodname> + <methodparam></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new mount operation. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giomountoperation--get-anonymous"> + <title>gio.MountOperation.get_anonymous</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_anonymous</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if mount operation is anonymous. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_anonymous</methodname>() method check to see whether + the mount operation is being used for an anonymous user + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-choice"> + <title>gio.MountOperation.get_choice</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_choice</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer containing an index of the user's + choice from the choice's list, or 0. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_anonymous</methodname>() method gets a choice + from the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-domain"> + <title>gio.MountOperation.get_domain</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_domain</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string set to the domain. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_domain</methodname>() method gets the domain + of the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-password"> + <title>gio.MountOperation.get_password</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_password</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the password within + the mountoperation. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_password</methodname>() method gets a password + from the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-password-save"> + <title>gio.MountOperation.get_password_save</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_password_save</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a + <xref linkend="gio-password-save-constants" endterm="gio-password-save-constants-title"></xref> + flag. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_password_save</methodname>() method gets the state + of saving passwords for the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--get-username"> + <title>gio.MountOperation.get_username</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_username</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a string containing the user name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_username</methodname>() method get the user + name from the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--reply"> + <title>gio.MountOperation.reply</title> + + <programlisting><methodsynopsis language="python"> + <methodname>reply</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>result</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-mount-operation-result-constants" endterm="gio-mount-operation-result-constants-title"></xref> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>reply</methodname>() method emits the "reply" signal. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-anonymous"> + <title>gio.MountOperation.set_anonymous</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_anonymous</methodname> + <methodparam><parameter role="keyword">anonymous</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>anonymous</parameter> :</term> + <listitem><simpara>boolean value. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_anonymous</methodname>() method sets the mount operation + to use an anonymous user if anonymous is <literal>True</literal>. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-choice"> + <title>gio.MountOperation.set_choice</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_choice</methodname> + <methodparam><parameter role="keyword">choice</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>choice</parameter> :</term> + <listitem><simpara>an integer. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_choice</methodname>() method sets a default choice for the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-domain"> + <title>gio.MountOperation.set_domain</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_domain</methodname> + <methodparam><parameter role="keyword">domain</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>domain</parameter> :</term> + <listitem><simpara>the domain to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_domain</methodname>() method sets the mount operation's domain. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-password"> + <title>gio.MountOperation.set_password</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_password</methodname> + <methodparam><parameter role="keyword">password</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>password</parameter> :</term> + <listitem><simpara>password to set. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_password</methodname>() method sets the mount + operation's password to password. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-password-save"> + <title>gio.MountOperation.set_password_save</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_password_save</methodname> + <methodparam><parameter role="keyword">save</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>save</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-password-save-constants" endterm="gio-password-save-constants-title"></xref> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_password_save</methodname>() method sets the state + of saving passwords for the mount operation. + </para> + </refsect2> + + <refsect2 id="method-giomountoperation--set-username"> + <title>gio.MountOperation.set_username</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_username</methodname> + <methodparam><parameter role="keyword">username</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>username</parameter> :</term> + <listitem><simpara>input username. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_anonymous</methodname>() method sets the user + name within op to username. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Signals</title> + + <refsect2 id="signal-giomountoperation--aborted"> + <title>The "aborted" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</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. + 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-giomountoperation--ask-password"> + <title>The "ask-password" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>default_user</parameter></methodparam> + <methodparam><parameter>default_domain</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>message</parameter> :</term> + <listitem><simpara>string containing a message to display to the user.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>default_user</parameter> :</term> + <listitem><simpara>string containing the default user name.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>default_domain</parameter> :</term> + <listitem><simpara>string containing the default domain.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>a set of + <xref linkend="gio-ask-password-flags-constants" endterm="gio-ask-password-flags-constants-title"></xref> + </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> + This signal is emitted when a mount operation asks the user for a password. + If the message contains a line break, the first line should be presented as a heading. + For example, it may be used as the primary text in a + <link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>. + </para> + </refsect2> + + <refsect2 id="signal-giomountoperation--ask-question"> + <title>The "ask-question" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>message</parameter></methodparam> + <methodparam><parameter>choices</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>message</parameter> :</term> + <listitem><simpara>string containing a message to display to the user.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>choices</parameter> :</term> + <listitem><simpara>a list of strings for each possible choice.</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> + This signal is emitted when asking the user a question and gives a list of choices + for the user to choose from. If the message contains a line break, the first line should be + presented as a heading. For example, it may be used as the primary text in a + <link linkend="class-gtkmessagedialog"><classname>gtk.MessageDialog</classname></link>. + </para> + </refsect2> + + <refsect2 id="signal-giomountoperation--reply"> + <title>The "reply" gio.MountOperation Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>mountoperation</parameter></methodparam> + <methodparam><parameter>result</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>mountoperation</parameter> :</term> + <listitem><simpara>the mountoperation</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>result</parameter> :</term> + <listitem><simpara>a + <xref linkend="gio-mount-operation-result-constants" endterm="gio-mount-operation-result-constants-title"></xref> + indicating how the request was handled</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> + This signal is emitted when the user has replied to the mount operation. + </para> + </refsect2> + + </refsect1> +</refentry> diff --git a/docs/reference/pygio-outputstream.xml b/docs/reference/pygio-outputstream.xml new file mode 100644 index 0000000..00ddf2e --- /dev/null +++ b/docs/reference/pygio-outputstream.xml @@ -0,0 +1,140 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giooutputstream"> + <refnamediv> + <refname>gio.OutputStream</refname> + <refpurpose>Base class for implementing streaming input</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.OutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--clear-pending">clear_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--close">close</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--close-async">close_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--close-finish">close_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--flush">flush</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--flush-async">flush_async</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--flush-finish">flush_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--has-pending">has_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--is-closed">is_closed</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--set-pending">set_pending</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--splice">splice</link></methodname> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.OUTPUT_STREAM_SPLICE_NONE</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--splice-async">splice_async</link></methodname> + <methodparam><parameter role="keyword">source</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>gio.OUTPUT_STREAM_SPLICE_NONE</initializer></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--splice-finish">splice_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--write">write</link></methodname> + <methodparam><parameter role="keyword">buffer</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--write-async">write_async</link></methodname> + <methodparam><parameter role="keyword">buffer</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">io_priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giooutputstream--write-finish">write_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + has functions to write from a stream ( + <methodname><link linkend="method-giooutputstream--write">gio.OutputStream.write</link></methodname>() + ), to close a stream ( + <methodname><link linkend="method-giooutputstream--close">gio.OutputStream.close</link></methodname>() + ) and to flush pending writes ( + <methodname><link linkend="method-giooutputstream--flush">gio.OutputStream.flush</link></methodname>() + ). + </para> + <para> + To copy the content of an input stream to an output stream without manually + handling the reads and writes, use + <methodname><link linkend="method-giooutputstream--splice">gio.OutputStream.splice</link></methodname>(). + </para> + <para> + All of these functions have async variants too. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + <para> Unfinished section, you may want to see the relevant C API docs for methods descriptions.</para> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-seekable.xml b/docs/reference/pygio-seekable.xml new file mode 100644 index 0000000..1081143 --- /dev/null +++ b/docs/reference/pygio-seekable.xml @@ -0,0 +1,231 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gioseekable"> + <refnamediv> + <refname>gio.Seekable</refname> + <refpurpose>Stream seeking interface.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Seekable</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioseekable--tell">tell</link></methodname> + </methodsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioseekable--can_seek">can_seek</link></methodname> + </methodsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioseekable--seek">seek</link></methodname> + <methodparam><parameter role="keyword">offset</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioseekable--can_truncate">can_truncate</link></methodname> + </methodsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-gioseekable--truncate">truncate</link></methodname> + <methodparam><parameter role="keyword">offset</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-gioseekable">gio.Seekable</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Known Implementation</title> + <para> + <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> is implemented by + <link linkend="class-giofileoutputstream"><classname>gio.FileOutputStream</classname></link>, + <link linkend="class-giomemoryinputstream"><classname>gio.MemoryInputStream</classname></link>, + <link linkend="class-giofileinputstream"><classname>gio.FileInputStream</classname></link> and + <link linkend="class-giomemoryoutputstream"><classname>gio.MemoryOutputStream</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-gioseekable"><classname>gio.Seekable</classname></link> + is implemented by streams (implementations of + <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> or + <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link>) + that support seeking. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gioseekable--tell"> + <title>gio.Seekable.tell</title> + + <programlisting><methodsynopsis language="python"> + <methodname>tell</methodname> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara> + the offset from the beginning of the buffer + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Tells the current position within the stream. + </para> + </refsect2> + + <refsect2 id="method-gioseekable--can_seek"> + <title>gio.Seekable.can_seek</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_seek</methodname> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if this + <classname>gio.Seekable</classname> can be seeked with + the <methodname>seek</methodname>() method, <literal>False</literal> + if not. </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_seek</methodname>() method checks if the + <link linkend="method-gioseekable--seek"><methodname>seek</methodname>()</link> + can be used on this <classname>gio.Seekable</classname>. + </para> + </refsect2> + <refsect2 id="method-gioseekable--seek"> + <title>gio.Seekable.seek</title> + + <programlisting><methodsynopsis language="python"> + <methodname>seek</methodname> + <methodparam><parameter role="keyword">offset</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>offset</parameter> :</term> + <listitem><simpara>the offset that is added to the position determined by the <literal>type</literal> parameter. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>0=current position, 1=start of the file, 2=end of the file.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>a <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + or <literal>None</literal>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> on successful seek, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Seeks in the stream by the given <literal>offset</literal>, modified by <literal>type</literal>. + </para> + <para> + If <literal>cancellable</literal> is not <literal>None</literal>, then the + operation can be cancelled by triggering the cancellable object from another thread. + </para> + </refsect2> + <refsect2 id="method-gioseekable--can_truncate"> + <title>gio.Seekable.can_truncate</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_truncate</methodname> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if this + <classname>gio.Seekable</classname> can be truncated with + the <methodname>truncate</methodname>() method, <literal>False</literal> + if not. </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_truncate</methodname>() method checks if the + <link linkend="method-gioseekable--truncate"><methodname>truncate</methodname>()</link> + can be used on this <classname>gio.Seekable</classname>. + </para> + </refsect2> + <refsect2 id="method-gioseekable--truncate"> + <title>gio.Seekable.truncate</title> + + <programlisting><methodsynopsis language="python"> + <methodname>truncate</methodname> + <methodparam><parameter role="keyword">offset</parameter></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>offset</parameter> :</term> + <listitem><simpara>the offset at which the stream should be truncated + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>cancellable</parameter> :</term> + <listitem><simpara>a <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + or <literal>None</literal>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if successful, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Truncates a stream with a given <literal>offset</literal>. + </para> + <para> + If <literal>cancellable</literal> is not <literal>None</literal>, then the + operation can be cancelled by triggering the cancellable object from another thread. + </para> + <para> + If an operation was partially finished when the operation was cancelled the + partial result will be returned, without an error. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-simpleasyncresult.xml b/docs/reference/pygio-simpleasyncresult.xml new file mode 100644 index 0000000..f6a0787 --- /dev/null +++ b/docs/reference/pygio-simpleasyncresult.xml @@ -0,0 +1,317 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giosimpleasyncresult"> + <refnamediv> + <refname>gio.SimpleAsyncResult</refname> + <refpurpose>Simple asynchronous results implementation.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.SimpleAsyncResult</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--complete">complete</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">complete_in_idle</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gboolean">get_op_res_gboolean</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gssize">get_op_res_gssize</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--propagate-error">propagate_error</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--set-handle-cancellation">set_handle_cancellation</link></methodname> + <methodparam><parameter role="keyword">handle_cancellation</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gboolean">set_op_res_gboolean</link></methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gssize">set_op_res_gssize</link></methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giosimpleasyncresult">gio.SimpleAsyncResult</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Implemented Interface</title> + <para> + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> implements + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </para> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + Implements <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + for simple cases. Most of the time, this will be all an application needs, and will be used transparently + Because of this, GSimpleAsyncResult is used throughout GIO for handling asynchronous functions. + </para> + <para> + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> + handles GAsyncReadyCallbacks, error reporting, operation cancellation and the final state of an + operation, completely transparent to the application. Results can be returned as a pointer e.g. + for functions that return data that is collected asynchronously, a boolean value for checking the + success or failure of an operation, or a gssize for operations which return the number of bytes modified + by the operation; all of the simple return cases are covered. + </para> + <para> + Most of the time, an application will not need to know of the details of this API; it is handled + transparently, and any necessary operations are handled by GAsyncResult's interface. However, if + implementing a new GIO module, for writing language bindings, or for complex applications that need + better control of how asynchronous operations are completed, it is important to understand this functionality. + </para> + <para> + <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link> + are tagged with the calling function to ensure that asynchronous functions and + their finishing functions are used together correctly. + </para> + <!-- NEEDS LOVE + <para> + To create a new <link linkend="class-giosimpleasyncresult"><classname>gio.SimpleAsyncResult</classname></link>, + call g_simple_async_result_new(). If the result needs to be created for a GError, use g_simple_async_result_new_from_error(). + If a GError is not available (e.g. the asynchronous operation's doesn't take a GError argument), but the result still needs + to be created for an error condition, use g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() + if your application or binding requires passing a variable argument list directly), and the error can then be propegated + through the use of g_simple_async_result_propagate_error(). + </para> + --> + <para> + An asynchronous operation can be made to ignore a cancellation event by calling + <methodname><link linkend="method-giosimpleasyncresult--set-handle-cancellation">gio.SimpleAsyncResult.set_handle_cancellation</link></methodname>() + with a + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + for the operation and <literal>False</literal>. This is useful for operations that are dangerous to cancel, + such as close (which would cause a leak if cancelled before being run). + </para> + <para> + <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link> + can integrate into GLib's event loop, GMainLoop, or it can use GThreads if available. + <methodname><link linkend="method-giosimpleasyncresult--complete">gio.SimpleAsyncResult.complete</link></methodname>() + will finish an I/O task directly within the main event loop. + <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">gio.SimpleAsyncResult.complete_in_idle</link></methodname>() + will integrate the I/O task into the main event loop as an idle function. + <!-- + and g_simple_async_result_run_in_thread() + will run the job in a separate thread. + --> + </para> + <para> + To set the results of an asynchronous function, + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gboolean">gio.SimpleAsyncResult.set_op_res_gboolean</link></methodname>(), and + <methodname><link linkend="method-giosimpleasyncresult--set-op-res-gssize">gio.SimpleAsyncResult.set_op_res_gssize</link></methodname>() + are provided, setting the operation's result to a gboolean, or gssize, respectively. + </para> + <para> + Likewise, to get the result of an asynchronous function, + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gboolean">gio.SimpleAsyncResult.get_op_res_gboolean</link></methodname>() and + <methodname><link linkend="method-giosimpleasyncresult--get-op-res-gssize">gio.SimpleAsyncResult.get_op_res_gssize</link></methodname>() + are provided, getting the operation's result as a gboolean and gssize, respectively. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giosimpleasyncresult--complete"> + <title>gio.SimpleAsyncResult.complete</title> + + <programlisting><methodsynopsis language="python"> + <methodname>complete</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>complete</methodname>() method completes an asynchronous I/O job. + Must be called in the main thread, as it invokes the callback that should be called + in the main thread. If you are in a different thread use + <methodname><link linkend="method-giosimpleasyncresult--complete-in-idle">gio.SimpleAsyncResult.complete_in_idle</link></methodname>(). + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--complete-in-idle"> + <title>gio.SimpleAsyncResult.complete_in_idle</title> + + <programlisting><methodsynopsis language="python"> + <methodname>complete_in_idle</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + </variablelist> + + <para> + The <methodname>complete_in_idle</methodname>() method completes an asynchronous + function in the main event loop using an idle function. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--get-op-res-gboolean"> + <title>gio.SimpleAsyncResult.get_op_res_gboolean</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_op_res_gboolean</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the operation's result was + <literal>True</literal>, <literal>False</literal> if the operation's result + was <literal>False</literal>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_op_res_gboolean</methodname>() method gets the operation + result boolean from within the asynchronous result. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--get-op-res-gssize"> + <title>gio.SimpleAsyncResult.get_op_res_gssize</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_op_res_gssize</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a gssize returned from the asynchronous function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_op_res_gssize</methodname>() method gets a gssize + from the asynchronous result. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--propagate-error"> + <title>gio.SimpleAsyncResult.propagate_error</title> + + <programlisting><methodsynopsis language="python"> + <methodname>propagate_error</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the error was propegated + to dest. <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>propagate_error</methodname>() method propagates an error + from within the simple asynchronous result to a given destination. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--set-handle-cancellation"> + <title>gio.SimpleAsyncResult.set_handle_cancellation</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_handle_cancellation</methodname> + <methodparam><parameter role="keyword">handle_cancellation</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">handle_cancellation</parameter> :</term> + <listitem><simpara>a boolean. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_handle_cancellation</methodname>() method sets whether + to handle cancellation within the asynchronous operation. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--set-op-res-gboolean"> + <title>gio.SimpleAsyncResult.set_op_res_gboolean</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_op_res_gboolean</methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">op_res</parameter> :</term> + <listitem><simpara>a boolean. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_op_res_gboolean</methodname>() method sets the operation + result to a boolean within the asynchronous result. + </para> + </refsect2> + + <refsect2 id="method-giosimpleasyncresult--set-op-res-gssize"> + <title>gio.SimpleAsyncResult.set_op_res_gssize</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_op_res_gssize</methodname> + <methodparam><parameter role="keyword">op_res</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">op_res</parameter> :</term> + <listitem><simpara>a gssize. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_op_res_gssize</methodname>() method sets the operation + result within the asynchronous result to the given op_res. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-themedicon.xml b/docs/reference/pygio-themedicon.xml new file mode 100644 index 0000000..fe0e44c --- /dev/null +++ b/docs/reference/pygio-themedicon.xml @@ -0,0 +1,204 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giothemedicon"> + <refnamediv> + <refname>gio.ThemedIcon</refname> + <refpurpose>Icon theming support.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.ThemedIcon</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giothemedicon">gio.ThemedIcon</link></methodname> + <methodparam></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giothemedicon--append-name">append_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giothemedicon--get-names">get_names</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giothemedicon--prepend-name">prepend_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giothemedicon">gio.ThemedIcon</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giomountoperation"> + <title>gio.ThemedIcon Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"name"</entry> + <entry>Write/Contruct Only</entry> + <entry> + The icon name. Default value: <literal>None</literal> + </entry> + </row> + <row valign="top"> + <entry>"names"</entry> + <entry>Read/Write/Contruct Only</entry> + <entry> + A list of icon names. + </entry> + </row> + <row valign="top"> + <entry>"use-default-fallbacks"</entry> + <entry>Read/Write/Contruct Only</entry> + <entry> + Whether to use the default fallbacks found by shortening the + icon name at '-' characters. If the "names" array has more + than one element, ignores any past the first. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link> + is an implementation of <link linkend="class-gioicon"><classname>gio.Icon</classname></link> + that supports icon themes. GThemedIcon contains a list of all of the icons present in an icon + theme, so that icons can be looked up quickly. + </para> + <para> + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link> + does not provide actual pixmaps for icons, just the icon names. Ideally something like + <methodname><link linkend="method-gtkicontheme--choose-icon">gtk.IconTheme.choose_icon</link></methodname>() + should be used to resolve the list of names so that fallback icons work nicely + with themes that inherit other themes + </para> + </refsect1> + + <refsect1 id="constructor-giothemedicon"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.ThemedIcon</methodname> + <methodparam><parameter>name</parameter></methodparam> + <methodparam><parameter>use_default_fallbacks</parameter><initializer><literal>False</literal></initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>name</parameter> :</term> + <listitem><simpara>a string containing an icon name. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new themed icon from icon name, if instead of an icon name you + provide a list of icon names, the <link linkend="class-giothemedicon"><classname>gio.ThemedIcon</classname></link> + will be constructed using the items in the list. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giothemedicon--append-name"> + <title>gio.ThemedIcon.append_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>append_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>name</emphasis> :</term> + <listitem><simpara>name of icon to append to list of icons from within icon. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>append_name</methodname>() method appends a name to + the list of icons from within icon. + </para> + </refsect2> + + <refsect2 id="method-giothemedicon--get-names"> + <title>gio.ThemedIcon.get_names</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_names</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of icon names. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_names</methodname>() method gets the names + of icons from within icon. + </para> + </refsect2> + + <refsect2 id="method-giothemedicon--prepend-name"> + <title>gio.ThemedIcon.prepend_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>prepend_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>name</emphasis> :</term> + <listitem><simpara>name of icon to prepend to list of icons from within icon. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>prepend_name</methodname>() method prepends a name to + the list of icons from within icon. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-unixinputstream.xml b/docs/reference/pygio-unixinputstream.xml new file mode 100644 index 0000000..5ef4cde --- /dev/null +++ b/docs/reference/pygio-unixinputstream.xml @@ -0,0 +1,202 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giounixinputstream"> + <refnamediv> + <refname>gio.unix.InputStream</refname> + <refpurpose>Streaming input operations for UNIX file descriptors.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.unix.InputStream</classname></ooclass> + <ooclass><classname><link linkend="class-gioinputstream">gio.InputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giounixinputstream">gio.unix.InputStream</link></methodname> + <methodparam><parameter role="keyword">fd</parameter></methodparam> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giounixinputstream--get-close-fd">get_close_fd</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giounixinputstream--get-fd">get_fd</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giounixinputstream--set-close-fd">set_close_fd</link></methodname> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-gioinputstream">gio.InputStream</link> + +-- <link linkend="class-giounixinputstream">gio.unix.InputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giounixinputstream"> + <title>gio.unix.InputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"close-fd"</entry> + <entry>Read - Write</entry> + <entry>Whether to close the file descriptor when the stream is closed. + Default value: <literal>True</literal>.</entry> + </row> + <row valign="top"> + <entry>"fd"</entry> + <entry>Read - Write - Construct only</entry> + <entry>The file descriptor that the stream reads from. Default value: -1.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giounixinputstream"><classname>gio.unix.InputStream</classname></link> + implements <link linkend="class-gioinputstream"><classname>gio.InputStream</classname></link> + for reading from a UNIX file descriptor, including asynchronous operations. + The file descriptor must be selectable, so it doesn't work with opened files. + </para> + <para> + Note that <link linkend="class-giounixinputstream"><classname>gio.unix.InputStream</classname></link> + belongs to the UNIX-specific GIO interfaces, thus you have to use the gio-unix-2.0.pc pkg-config file + when using it. + </para> + </refsect1> + + <refsect1 id="constructor-giounixinputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.unix.InputStream</methodname> + <methodparam><parameter role="keyword">fd</parameter></methodparam> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter> :</term> + <listitem><simpara>a UNIX file descriptor. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>close_fd</parameter> :</term> + <listitem><simpara><literal>True</literal> + to close the file descriptor when done + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giounixinputstream"><classname>gio.unix.InputStream</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giounixinputstream"><classname>gio.unix.InputStream</classname></link> + from the given fd. + </para> + <para> + If close_fd is <literal>True</literal>, the file descriptor will be closed when the stream is closed. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giounixinputstream--get-close-fd"> + <title>gio.unix.InputStream.get_close_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_close_fd</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the file descriptor is closed when done. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_close_fd</methodname>() method returns whether the file + descriptor of stream will be closed when the stream is closed. + </para> + </refsect2> + + <refsect2 id="method-giounixinputstream--get-fd"> + <title>gio.unix.InputStream.get_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_fd</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The file descriptor of stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_fd</methodname>() method return the UNIX file descriptor + that the stream reads from. + </para> + </refsect2> + + <refsect2 id="method-giounixinputstream--set-close-fd"> + <title>gio.unix.InputStream.set_close_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_close_fd</methodname> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">close_fd</parameter> :</term> + <listitem><simpara><literal>True</literal> to close the file descriptor when done . + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_close_fd</methodname>() method sets whether the file descriptor + of stream shall be closed when the stream is closed. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-unixoutputstream.xml b/docs/reference/pygio-unixoutputstream.xml new file mode 100644 index 0000000..02e4be8 --- /dev/null +++ b/docs/reference/pygio-unixoutputstream.xml @@ -0,0 +1,202 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giounixoutputstream"> + <refnamediv> + <refname>gio.unix.OutputStream</refname> + <refpurpose>Streaming output operations for UNIX file descriptors.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.unix.OutputStream</classname></ooclass> + <ooclass><classname><link linkend="class-giooutputstream">gio.OutputStream</link></classname></ooclass> + + <constructorsynopsis language="python"> + <methodname><link linkend="constructor-giounixoutputstream">gio.unix.OutputStream</link></methodname> + <methodparam><parameter role="keyword">fd</parameter></methodparam> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </constructorsynopsis> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giounixoutputstream--get-close-fd">get_close_fd</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giounixoutputstream--get-fd">get_fd</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giounixoutputstream--set-close-fd">set_close_fd</link></methodname> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giooutputstream">gio.OutputStream</link> + +-- <link linkend="class-giounixoutputstream">gio.unix.OutputStream</link> +</synopsis> + + </refsect1> + + <refsect1 id="properties-giounixoutputstream"> + <title>gio.unix.OutputStream Properties</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + <row valign="top"> + <entry>"close-fd"</entry> + <entry>Read - Write</entry> + <entry>Whether to close the file descriptor when the stream is closed. + Default value: <literal>True</literal>.</entry> + </row> + <row valign="top"> + <entry>"fd"</entry> + <entry>Read - Write - Construct only</entry> + <entry>The file descriptor that the stream writes to. Default value: -1.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + <link linkend="class-giounixoutputstream"><classname>gio.unix.OutputStream</classname></link> + implements <link linkend="class-giooutputstream"><classname>gio.OutputStream</classname></link> + for writing to a UNIX file descriptor, including asynchronous operations. + The file descriptor must be selectable, so it doesn't work with opened files. + </para> + <para> + Note that <link linkend="class-giounixoutputstream"><classname>gio.unix.OutputStream</classname></link> + belongs to the UNIX-specific GIO interfaces, thus you have to use the gio-unix-2.0.pc pkg-config file + when using it. + </para> + </refsect1> + + <refsect1 id="constructor-giounixoutputstream"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>gio.unix.OutputStream</methodname> + <methodparam><parameter role="keyword">fd</parameter></methodparam> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter> :</term> + <listitem><simpara>a UNIX file descriptor. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>close_fd</parameter> :</term> + <listitem><simpara><literal>True</literal> + to close the file descriptor when done + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new + <link linkend="class-giounixoutputstream"><classname>gio.unix.OutputStream</classname></link> + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + Creates a new <link linkend="class-giounixoutputstream"><classname>gio.unix.OutputStream</classname></link> + from the given fd. + </para> + <para> + If close_fd is <literal>True</literal>, the file descriptor will be closed when the stream is closed. + </para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giounixoutputstream--get-close-fd"> + <title>gio.unix.OutputStream.get_close_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_close_fd</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the file descriptor is closed when done. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_close_fd</methodname>() method returns whether the file + descriptor of stream will be closed when the stream is closed. + </para> + </refsect2> + + <refsect2 id="method-giounixoutputstream--get-fd"> + <title>gio.unix.OutputStream.get_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_fd</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The file descriptor of stream. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_fd</methodname>() method return the UNIX file descriptor + that the stream reads from. + </para> + </refsect2> + + <refsect2 id="method-giounixoutputstream--set-close-fd"> + <title>gio.unix.OutputStream.set_close_fd</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_close_fd</methodname> + <methodparam><parameter role="keyword">close_fd</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">close_fd</parameter> :</term> + <listitem><simpara><literal>True</literal> to close the file descriptor when done . + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>set_close_fd</methodname>() method sets whether the file descriptor + of stream shall be closed when the stream is closed. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygio-volume.xml b/docs/reference/pygio-volume.xml new file mode 100644 index 0000000..cf0fa50 --- /dev/null +++ b/docs/reference/pygio-volume.xml @@ -0,0 +1,718 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giovolume"> + <refnamediv> + <refname>gio.Volume</refname> + <refpurpose>Volume management.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.Volume</classname></ooclass> + <ooclass><classname><link linkend="class-gobjectginterface">gobject.GInterface</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--can-eject">can_eject</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--can-mount">can_mount</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--eject">eject</link></methodname> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--eject-finish">eject_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--enumerate-identifiers">enumerate_identifiers</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-activation-root">get_activation_root</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-drive">get_drive</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-icon">get_icon</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-identifier">get_identifier</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-mount">get_mount</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-name">get_name</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--get-uuid">get_uuid</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--mount">mount</link></methodname> + <methodparam><parameter role="keyword">mount_operation</parameter></methodparam> + <methodparam><parameter role="keyword">callback</parameter></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_MOUNT_NONE</literal></initializer></methodparam> + <methodparam><parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--mount-finish">mount_finish</link></methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolume--should-automount">should_automount</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> + +-- <link linkend="class-giovolume">gio.Volume</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Prerequisites</title> + <para> + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> requires + <link linkend="class-gobject"><classname>gobject.GObject</classname></link> + </para> + </refsect1> + + <refsect1 id="signal-prototypes-giovolume"> + <title>gio.Volume Signal Prototypes</title> + + <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> + + <variablelist> + <varlistentry> + <term><link linkend="signal-giovolume--changed">"changed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolume--removed">"removed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + interface represents user-visible objects that can be mounted. Note, when porting + from GnomeVFS, <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + is the moral equivalent of GnomeVFSDrive. + </para> + <para> + Mounting a <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + instance is an asynchronous operation. For more information about asynchronous operations. + To mount a <link linkend="class-giovolume"><classname>gio.Volume</classname></link>, first call + <methodname><link linkend="method-giovolume--mount">gio.Volume.mount</link></methodname>() + with (at least) the <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + instance, optionally a + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + object and a GAsyncReadyCallback. + </para> + <para> + Typically, one will only want to pass <literal>None</literal> for the GMountOperation + if automounting all volumes when a desktop session starts since it's not desirable + to put up a lot of dialogs asking for credentials. + </para> + <para> + The callback will be fired when the operation has resolved (either with success or failure), + and a GAsyncReady structure will be passed to the callback. That callback should then call + <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>() + with the GVolume instance and the GAsyncReady data to see if the operation was completed + successfully. If an error is present when + <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>() + is called, then it will be filled with any error information. + </para> + <para> + It is sometimes necessary to directly access the underlying operating system object behind a volume + (e.g. for passing a volume to an application via the commandline). For this purpose, GIO allows to obtain + an 'identifier' for the volume. There can be different kinds of identifiers, such as Hal UDIs, + filesystem labels, traditional Unix devices (e.g. /dev/sda2), uuids. GIO uses predefind strings + as names for the different kinds of identifiers: + "hal-udi", "label", etc. Use + <methodname><link linkend="method-giovolume--get-identifier">gio.Volume.get_identifier</link></methodname>() + to obtain an identifier for a volume. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giovolume--can-eject"> + <title>gio.Volume.can_eject</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_eject</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the volume can be ejected, + <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_eject</methodname>() method checks if a volume can be ejected. + </para> + </refsect2> + + <refsect2 id="method-giovolume--can-mount"> + <title>gio.Volume.can_mount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>can_mount</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the volume can be mounted + for media changes, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>can_mount</methodname>() method checks if a volume + can be mounted. + </para> + </refsect2> + + <refsect2 id="method-giovolume--eject"> + <title>gio.Volume.eject</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject</methodname> + <methodparam> + <parameter role="keyword">callback</parameter> + </methodparam> + <methodparam> + <parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_UNMOUNT_NONE</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags affecting the unmount if required for eject. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject</methodname>() method asynchronously ejects a volume. + </para> + <para> + When the operation is finished, callback will be called. You can then call + <methodname><link linkend="method-giovolume--eject-finish">gio.Volume.eject_finish</link></methodname>() + to obtain the result of the operation. + </para> + </refsect2> + + <refsect2 id="method-giovolume--eject-finish"> + <title>gio.Volume.eject_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>eject_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the volume has been ejected + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>eject_finish</methodname>() method finishes ejecting a volume. + If any errors occured during the operation, error will be set to contain the + errors and <literal>False</literal> will be returned. + </para> + </refsect2> + + <refsect2 id="method-giovolume--enumerate-identifiers"> + <title>gio.Volume.enumerate_identifiers</title> + + <programlisting><methodsynopsis language="python"> + <methodname>enumerate_identifiers</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of strings containing kinds of identifiers. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>enumerate_identifiers</methodname>() method gets the kinds + of identifiers that volume has. Use + <methodname><link linkend="method-giovolume--get-identifier">gio.Volume.get_identifier</link></methodname>() + to obtain the identifiers themselves. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-activation-root"> + <title>gio.Volume.get_activation_root</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_activation_root</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the activation root of volume or <literal>None</literal>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_activation_root</methodname>() method gets the activation + root for a <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + if it is known ahead of mount time. Returns <literal>None</literal> otherwise. + If not <literal>None</literal> and if volume is mounted, then the result of + <methodname><link linkend="method-giomount--get-root">gio.Mount.get_root</link></methodname>() + on the GMount object obtained from + <methodname><link linkend="method-giovolume--get-mount">gio.Volume.get_mount</link></methodname>() + will always either be equal or a prefix of what this function returns. + In other words, in code: + </para> +<programlisting> +mount = volume.get_mount() # mounted, so never None +mount_root = mount.get_root() +volume_activation_root = volume.get_activation_root() # assume not None +</programlisting> + <para> + then the expression + </para> +<programlisting> +volume_activation_root.has_prefix(mount_root) || volume_activation_root.equal(mount_root) +</programlisting> + <para> + will always be <literal>True</literal>. + </para> + <para> + Activation roots are typically used in + <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link> + implementations to find the underlying mount to shadow, see + <methodname><link linkend="method-giomount--is-shadowed">gio.Mount.is_shadowed</link></methodname>() + for more details. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-drive"> + <title>gio.Volume.get_drive</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_drive</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A <link linkend="class-giodrive"><classname>gio.Drive</classname></link> + or <literal>None</literal> if volume is not associated with a drive. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_drive</methodname>() method gets the drive for the volume. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-icon"> + <title>gio.Volume.get_icon</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_icon</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><link linkend="class-gioicon"><classname>gio.Icon</classname></link> + for the volume. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_icon</methodname>() method gets the icon for volume. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-identifier"> + <title>gio.Volume.get_identifier</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_identifier</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A string containing the requested identfier, or + <literal>None</literal> if the + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + doesn't have this kind of identifier. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_identifier</methodname>() method gets the identifier of + the given kind for volume. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-mount"> + <title>gio.Volume.get_mount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_mount</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + or <literal>None</literal> if volume isn't mounted. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_mount</methodname>() method gets the mount for the volume. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-name"> + <title>gio.Volume.get_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_name</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A string containing volume's name. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_name</methodname>() method gets the name of volume. + </para> + </refsect2> + + <refsect2 id="method-giovolume--get-uuid"> + <title>gio.Volume.get_uuid</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_uuid</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the UUID for volume or <literal>None</literal> + if no UUID can be computed. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_uuid</methodname>() method gets the UUID for the volume. + The reference is typically based on the file system UUID for the volume in + question and should be considered an opaque string. + Returns <literal>None</literal> if there is no UUID available. + </para> + </refsect2> + + <refsect2 id="method-giovolume--mount"> + <title>gio.Volume.mount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>mount</methodname> + <methodparam> + <parameter role="keyword">mount_operation</parameter> + </methodparam> + <methodparam> + <parameter role="keyword">callback</parameter> + </methodparam> + <methodparam> + <parameter role="keyword">flags</parameter><initializer><literal>gio.MOUNT_MOUNT_NONE</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">cancellable</parameter><initializer><literal>None</literal></initializer> + </methodparam> + <methodparam> + <parameter role="keyword">user_data</parameter><initializer><literal>None</literal></initializer> + </methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">mount_operation</parameter> :</term> + <listitem><simpara>A + <link linkend="class-giomountoperation"><classname>gio.MountOperation</classname></link> + or <literal>None</literal> to avoid user interaction. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">callback</parameter> :</term> + <listitem><simpara>A GAsyncReadyCallback to call when the request is satisfied. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>Flags affecting the operation + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">cancellable</parameter> :</term> + <listitem><simpara>Optional + <link linkend="class-giocancellable"><classname>gio.Cancellable</classname></link> + object, <literal>None</literal> to ignore. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>The data to pass to callback function. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>mount</methodname>() method mounts a volume. This is an + asynchronous operation, and is finished by calling + <methodname><link linkend="method-giovolume--mount-finish">gio.Volume.mount_finish</link></methodname>() + with the volume and GAsyncResult returned in the callback. + </para> + </refsect2> + + <refsect2 id="method-giovolume--mount-finish"> + <title>gio.Volume.mount_finish</title> + + <programlisting><methodsynopsis language="python"> + <methodname>mount_finish</methodname> + <methodparam><parameter role="keyword">result</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">result</parameter> :</term> + <listitem><simpara>a <link linkend="class-gioasyncresult"><classname>gio.AsyncResult</classname></link>. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the volume has been mounted + successfully, <literal>False</literal> otherwise. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>mounted</methodname>() method finishes mounting a volume. + If any errors occured during the operation, error will be set to contain + the errors and <literal>False</literal> will be returned. + </para> + <para> + If the mount operation succeeded, + <methodname><link linkend="method-giovolume--get-mount">get_mount</link></methodname>() + on volume is guaranteed to return the mount right after calling this function; + there's no need to listen for the 'mount-added' signal on + <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link>. + </para> + </refsect2> + + <refsect2 id="method-giovolume--should-automount"> + <title>gio.Volume.should_automount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>should_automount</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>True</literal> if the volume should + be automatically mounted. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>should_automount</methodname>() method returns whether + the volume should be automatically mounted. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Signals</title> + + <refsect2 id="signal-giovolume--changed"> + <title>The "changed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume</parameter> :</term> + <listitem><simpara>the volume</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 when the volume has been changed. + </para> + </refsect2> + + <refsect2 id="signal-giovolume--removed"> + <title>The "removed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume</parameter> :</term> + <listitem><simpara>the volume</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> + This signal is emitted when the + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + have been removed. If the recipient is holding references to the object + they should release them so the object can be finalized. + </para> + </refsect2> + + </refsect1> +</refentry> diff --git a/docs/reference/pygio-volumemonitor.xml b/docs/reference/pygio-volumemonitor.xml new file mode 100644 index 0000000..399d07e --- /dev/null +++ b/docs/reference/pygio-volumemonitor.xml @@ -0,0 +1,844 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-giovolumemonitor"> + <refnamediv> + <refname>gio.VolumeMonitor</refname> + <refpurpose>Volume Monitor.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <classsynopsis language="python"> + <ooclass><classname>gio.VolumeMonitor</classname></ooclass> + <ooclass><classname><link linkend="class-gobject">gobject.GObject</link></classname></ooclass> + + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolumemonitor--get-connected-drives">get_connected_drives</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolumemonitor--get-mount-for-uuid">get_mount_for_uuid</link></methodname> + <methodparam><parameter role="keyword">uuid</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolumemonitor--get-mounts">get_mounts</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolumemonitor--get-volume-for-uuid">get_volume_for_uuid</link></methodname> + <methodparam><parameter role="keyword">uuid</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link linkend="method-giovolumemonitor--get-volumes">get_volumes</link></methodname> + <methodparam></methodparam> + </methodsynopsis> + + </classsynopsis> + +<programlisting> +<emphasis role="bold">Functions</emphasis> +<methodsynopsis language="python"> + <methodname><link linkend="function-gio--volume-monitor-adopt-orphan-mount">gio.volume_monitor_adopt_orphan_mount</link></methodname> + <methodparam></methodparam> +</methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-gio--volume-monitor-get">gio.volume_monitor_get</link></methodname> + <methodparam></methodparam> +</methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> + +-- <link linkend="class-giovolumemonitor">gio.VolumeMonitor</link> +</synopsis> + + </refsect1> + + <refsect1 id="signal-prototypes-giovolumemonitor"> + <title>gio.VolumeMonitor Signal Prototypes</title> + + <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> + + <variablelist> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--drive-changed">"drive-changed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--drive-connected">"drive-connected"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--drive-disconnected">"drive-disconnected"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--drive-eject-button">"drive-eject-button"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--mount-added">"mount-added"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--mount-changed">"mount-changed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--mount-pre-unmount">"mount-pre-unmount"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--mount-removed">"mount-removed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--volume-added">"volume-added"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--volume-changed">"volume-changed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + <varlistentry> + <term><link linkend="signal-giovolumemonitor--volume-removed">"volume-removed"</link></term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + + <para> + The <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link> + is for listing the user interesting devices and volumes on the computer. In other words, + what a file selector or file manager would show in a sidebar. + </para> + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-giovolumemonitor--get-connected-drives"> + <title>gio.VolumeMonitor.get_connected_drives</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_connected_drives</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of connected + <link linkend="class-giodrive"><classname>gio.Drive</classname></link> objects. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_connected_drives</methodname>() method gets a list + of drives connected to the system. + </para> + </refsect2> + + <refsect2 id="method-giovolumemonitor--get-mount-for-uuid"> + <title>gio.VolumeMonitor.get_mount_for_uuid</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_mount_for_uuid</methodname> + <methodparam><parameter role="keyword">uuid</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">uuid</parameter> :</term> + <listitem><simpara>The UUID to look for. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + or <literal>None</literal> if no such mount is available. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_mount_for_uuid</methodname>() method finds a + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + object by it's UUID (see + <methodname><link linkend="method-giomount--get-uuid">gio.Mount.get_uuid</link></methodname>()) + </para> + </refsect2> + + <refsect2 id="method-giovolumemonitor--get-mounts"> + <title>gio.VolumeMonitor.get_mounts</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_mounts</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list of + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + objects. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_mounts</methodname>() method gets a list of the mounts on the system. + </para> + </refsect2> + + <refsect2 id="method-giovolumemonitor--get-volume-for-uuid"> + <title>gio.VolumeMonitor.get_volume_for_uuid</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_volume_for_uuid</methodname> + <methodparam><parameter role="keyword">uuid</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter role="keyword">uuid</parameter> :</term> + <listitem><simpara>The UUID to look for. + </simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + or <literal>None</literal> if no such volume is available. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_mount_for_uuid</methodname>() method finds a + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + object by it's UUID (see + <methodname><link linkend="method-giomount--get-uuid">gio.Mount.get_uuid</link></methodname>()) + </para> + </refsect2> + + <refsect2 id="method-giovolumemonitor--get-volumes"> + <title>gio.VolumeMonitor.get_volumes</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_volumes</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A list of + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + objects. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>get_volumes</methodname>() method gets a list of the volumes on the system. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gio--volume-monitor-adopt-orphan-mount"> + <title>gio.volume_monitor_adopt_orphan_mount</title> + + <programlisting><methodsynopsis language="python"> + <methodname>volume_monitor_adopt_orphan_mount</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>The <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + object that is the parent for mount or <literal>None</literal> if no wants to adopt the + <link linkend="class-giomount"><classname>gio.Mount</classname></link>. + </simpara></listitem> + </varlistentry> + </variablelist> + + <warning> + <para>This method will be deprecated starting from GIO 2.20</para> + </warning> + + <para> + The <methodname>volume_monitor_adopt_orphan_mount</methodname>() function should + be called by any <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link> + implementation when a new <link linkend="class-giomount"><classname>gio.Mount</classname></link> + object is created that is not associated with a + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> object. + It must be called just before emitting the mount_added signal. + </para> + <para> + If the return value is not <literal>None</literal>, the caller must associate the returned + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + object with the + <link linkend="class-giomount"><classname>gio.Mount</classname></link>. + This involves returning it in it's + <methodname><link linkend="method-giomount--get-volumes">gio.Mount.get_volumes</link></methodname>() + implementation. The caller must also listen for the "removed" signal on the + returned object and give up it's reference when handling that signal + </para> + <para> + Similary, if implementing + <methodname><link linkend="function-gio--volume-monitor-adopt-orphan-mount">gio.volume_monitor_adopt_orphan_mount</link></methodname>(), + the implementor must take a reference to mount and return it in it's + <methodname><link linkend="method-giovolume--get-mount">gio.Volume.get_mount</link></methodname>() + implemented. Also, the implementor must listen for the "unmounted" signal + on mount and give up it's reference upon handling that signal. + </para> + <para> + There are two main use cases for this function. + </para> + <para> + One is when implementing a user space file system driver that reads blocks of + a block device that is already represented by the native volume monitor + (for example a CD Audio file system driver). Such a driver will generate it's own + <link linkend="class-giomount"><classname>gio.Mount</classname></link> + object that needs to be assoicated with the + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + object that represents the volume. + </para> + <para> + The other is for implementing a + <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link> + whose sole purpose is to return + <link linkend="class-giovolume"><classname>gio.Volume</classname></link> + objects representing entries in the users "favorite servers" list or similar. + </para> + </refsect2> + + <refsect2 id="function-gio--volume-monitor-get"> + <title>gio.volume_monitor_get</title> + + <programlisting><methodsynopsis language="python"> + <methodname>volume_monitor_get</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>A reference to the + <link linkend="class-giovolumemonitor"><classname>gio.VolumeMonitor</classname></link> + used by gio. + </simpara></listitem> + </varlistentry> + </variablelist> + + <para> + The <methodname>volume_monitor_get</methodname>() function gets the + volume monitor used by gio. + </para> + </refsect2> + </refsect1> + + <refsect1> + <title>Signals</title> + + <refsect2 id="signal-giovolumemonitor--drive-changed"> + <title>The "drive-changed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>drive</parameter> :</term> + <listitem><simpara>the drive that changed</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 when a drive changes. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--drive-connected"> + <title>The "drive-connected" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>drive</parameter> :</term> + <listitem><simpara>the drive that was connected</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 when a drive is connected to the system. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--drive-disconnected"> + <title>The "drive-disconnected" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>drive</parameter> :</term> + <listitem><simpara>the drive that was disconnected</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 when a drive is disconnected from the system. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--drive-eject-button"> + <title>The "drive-eject-button" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>drive</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>drive</parameter> :</term> + <listitem><simpara>the drive where the eject button was pressed</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 when the eject button is pressed on drive. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--mount-added"> + <title>The "mount-added" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>mount</parameter> :</term> + <listitem><simpara>a Mount that was added.</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 when a mount is added. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--mount-changed"> + <title>The "mount-changed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>mount</parameter> :</term> + <listitem><simpara>the Mount that changed.</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 when a mount changes. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--mount-pre-unmount"> + <title>The "mount-pre-unmount" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>mount</parameter> :</term> + <listitem><simpara>the Mount that is being unmounted.</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 when a mount is about to be removed. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--mount-removed"> + <title>The "mount-removed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>mount</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>mount</parameter> :</term> + <listitem><simpara>the Mount that was removed.</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 when a mount is removed. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--volume-added"> + <title>The "volume-added" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>volume</parameter> :</term> + <listitem><simpara>a Volume that was added.</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 when a mountable volume is added to the system. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--volume-changed"> + <title>The "volume-changed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>volume</parameter> :</term> + <listitem><simpara>a Volume that changed.</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 when mountable volume is changed. + </para> + </refsect2> + + <refsect2 id="signal-giovolumemonitor--volume-removed"> + <title>The "volume-removed" gio.Volume Signal</title> + + <programlisting><methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>volume_monitor</parameter></methodparam> + <methodparam><parameter>volume</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>volume_monitor</parameter> :</term> + <listitem><simpara>the volume monitor</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>volume</parameter> :</term> + <listitem><simpara>a Volume that was removed.</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 when a mountable volume is removed from the system. + </para> + </refsect2> + </refsect1> +</refentry> diff --git a/docs/reference/pygiounix-classes.xml b/docs/reference/pygiounix-classes.xml new file mode 100644 index 0000000..72b0081 --- /dev/null +++ b/docs/reference/pygiounix-classes.xml @@ -0,0 +1,13 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<chapter id="giounix-class-reference" + xmlns:xi="http://www.w3.org/2001/XInclude"> + +<title>PyGio Unix Class Reference</title> + +<!-- GIOUNIX CLASSES --> +<xi:include href="pygio-unixinputstream.xml"/> +<xi:include href="pygio-unixoutputstream.xml"/> + +</chapter> diff --git a/docs/reference/pyglib-classes.xml b/docs/reference/pyglib-classes.xml new file mode 100644 index 0000000..ecc4e5b --- /dev/null +++ b/docs/reference/pyglib-classes.xml @@ -0,0 +1,15 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<chapter id="glib-class-reference" + xmlns:xi="http://www.w3.org/2001/XInclude"> + +<title>PyGlibClass Reference</title> + +<!-- GLIB CLASSES --> +<xi:include href="pyglib-maincontext.xml"/> +<xi:include href="pyglib-mainloop.xml"/> +<xi:include href="pyglib-functions.xml"/> +<xi:include href="pyglib-constants.xml"/> + +</chapter> diff --git a/docs/reference/pyglib-constants.xml b/docs/reference/pyglib-constants.xml new file mode 100644 index 0000000..0f1bf8d --- /dev/null +++ b/docs/reference/pyglib-constants.xml @@ -0,0 +1,282 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="glib-constants"> + <refnamediv> + <refname>glib Constants</refname> + <refpurpose>the built-in constants of the glib module</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<xref linkend="glib-io-condition-constants" endterm="glib-io-condition-constants-title"></xref> +<xref linkend="glib-priority-constants" endterm="glib-priority-constants-title"></xref> +<xref linkend="glib-spawn-flag-constants" endterm="glib-spawn-flag-constants-title"></xref> +<xref linkend="glib-user-directory-constants" endterm="glib-user-directory-constants-title"></xref> +<xref linkend="glib-version-constants" endterm="glib-version-constants-title"></xref> +</programlisting> + + </refsect1> + + <refsect1 id="glib-constants-description"> + <title>Description</title> + + <refsect2 id="glib-io-condition-constants"> + <title id="glib-io-condition-constants-title">Glib IO Condition Constants</title> + + <para>The IO Condition constants are a set of bit-flags that specify a +condition to watch for on an event source.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.IO_IN</literal></term> + <listitem> + <simpara>There is data to read</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for + pipes and sockets).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_NVAL</literal></term> + <listitem> + <simpara>Invalid request. The file descriptor is not + open.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="glib-priority-constants"> + <title id="glib-priority-constants-title">Glib Priority Constants</title> + + <para>The Priority constants specify </para> + + <variablelist> + <varlistentry> + <term><literal>glib.PRIORITY_HIGH</literal></term> + <listitem> + <simpara>Use this for high priority event sources.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_DEFAULT</literal></term> + <listitem> + <simpara>Use this for default priority event sources. This + priority is used when adding timeout functions with the <link + linkend="function-glib--timeout-add"><function>glib.timeout_add</function>()</link> + function. This priority is also used for events from the X + server.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_HIGH_IDLE</literal></term> + <listitem> + <simpara>Use this for high priority idle functions. For example, + glib.PRIORITY_HIGH_IDLE + 10 is used for resizing operations; + and, glib.PRIORITY_HIGH_IDLE + 20, for redrawing + operations. (This is done to ensure that any pending resizes are + processed before any pending redraws, so that widgets are not + redrawn twice unnecessarily.)</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_DEFAULT_IDLE</literal></term> + <listitem> + <simpara>Use this for default priority idle functions. This + priority is used when adding idle functions with the <link + linkend="function-glib--idle-add"><function>glib.idle_add</function>()</link> + function.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.PRIORITY_LOW</literal></term> + <listitem> + <simpara>Use this for very low priority background + tasks.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="glib-spawn-flag-constants"> + <title id="glib-spawn-flag-constants-title">Glib Spawn Flag Constants</title> + + <para>The Spawn Flag constants are a set of bit-flags that can be +passed to the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +function.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal></term> + <listitem> + <simpara>the parent's open file descriptors will be inherited by +the child; otherwise all descriptors except stdin/stdout/stderr will be +closed before calling <function>exec</function>() in the child.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal></term> + <listitem> + <simpara>the child will not be automatically reaped; you must +call <function>waitpid</function>() or handle <literal>SIGCHLD</literal> +yourself, or the child will become a zombie.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_SEARCH_PATH</literal></term> + <listitem> + <simpara><parameter>argv</parameter>[0] need not be an absolute +path, it will be looked for in the user's <envar>PATH</envar>.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_STDOUT_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard output will be discarded, instead +of going to the same location as the parent's standard output.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_STDERR_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard error will be discarded.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_CHILD_INHERITS_STDIN</literal></term> + <listitem> + <simpara>the child will inherit the parent's standard input (by +default, the child's standard input is attached to /dev/null).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.SPAWN_FILE_AND_ARGV_ZERO</literal></term> + <listitem> + <simpara>the first element of <parameter>argv</parameter> is the +file to execute, while the remaining elements are the actual argument vector +to pass to the file. Normally <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +uses <parameter>argv</parameter>[0] as the file to execute, and passes all +of <parameter>argv</parameter> to the child.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="glib-user-directory-constants"> + <title id="glib-user-directory-constants-title">Glib User Directory Constants</title> + + <para>The User Directory constants are integer values that are currently used only as arguments to + <link linkend="function-glib--get-user-special-dir"><function>glib.get_user_special_dir</function>()</link> + function. See function documentation for details.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_DESKTOP</literal></term> + <listitem> + <simpara>the user's Desktop directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_DOCUMENTS</literal></term> + <listitem> + <simpara>the user's Documents directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_DOWNLOAD</literal></term> + <listitem> + <simpara>the user's Downloads directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_MUSIC</literal></term> + <listitem> + <simpara>the user's Music directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_PICTURES</literal></term> + <listitem> + <simpara>the user's Pictures directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_PUBLIC_SHARE</literal></term> + <listitem> + <simpara>the user's shared directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_TEMPLATES</literal></term> + <listitem> + <simpara>the user's Templates directory</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.USER_DIRECTORY_VIDEOS</literal></term> + <listitem> + <simpara>the user's Movies directory</simpara> + </listitem> + </varlistentry> + </variablelist> + </refsect2> + + <refsect2 id="glib-version-constants"> + <title id="glib-version-constants-title">Glib Version Constants</title> + <para>The Version constants specify the version of +<literal>Glib</literal> used by PyGObject as a 3-tuple containing the major, +minor and patch release numbers.</para> + + <variablelist> + <varlistentry> + <term><literal>glib.glib_version</literal></term> + <listitem> + <simpara>A 3-tuple containing (major, minor, patch) release + numbers of glib.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.pyglib_version</literal></term> + <listitem> + <simpara>A 3-tuple containing (major, minor, patch) release + numbers of the python bindings.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pyglib-functions.xml b/docs/reference/pyglib-functions.xml new file mode 100644 index 0000000..358fa83 --- /dev/null +++ b/docs/reference/pyglib-functions.xml @@ -0,0 +1,1047 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="glib-functions"> + <refnamediv> + <refname>glib Functions</refname> + <refpurpose>miscellaneous functions</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-glib--idle-add">glib.idle_add</link></methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--timeout-add">glib.timeout_add</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--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> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--source-remove">glib.source_remove</link></methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--main-context-default">glib.main_context_default</link></methodname> + <methodparam></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--markup-escape-text">glib.markup_escape_text</link></methodname> + <methodparam><parameter role="keyword">text</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link linkend="function-glib--child-watch-add">glib.child_watch_add</link></methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--spawn-async">glib.spawn_async</link></methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--get-current-time">glib.get_current_time</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-cache-dir">glib.get_user_cache_dir</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-config-dir">glib.get_user_config_dir</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-data-dir">glib.get_user_data_dir</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link + linkend="function-glib--get-user-special-dir">glib.get_user_special_dir</link></methodname> + <methodparam><parameter role="keyword">directory</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--main-depth">glib.main_depth</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--threads-init">glib.threads_init</link></methodname> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--filename-display-name">glib.filename_display_name</link></methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--filename-display-basename">glib.filename_display_basename</link></methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-glib--filename-from-utf8">glib.filename_from_utf8</link></methodname> + <methodparam><parameter>utf8string</parameter></methodparam> + </methodsynopsis></programlisting> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>These functions are part of the <literal>PyGObject</literal> glib +module but are not directly associated with a specific class.</para> + + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-glib--idle-add"> + <title>glib.idle_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.idle_add</methodname> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call when +<literal>PyGTK</literal> is idle</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>optionals arguments to be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.idle_add</function>() function adds a +function (specified by <parameter>callback</parameter>) to be called +whenever there are no higher priority events pending to the default main +loop. The function is given the default idle priority, +<literal>glib.PRIORITY_DEFAULT_IDLE</literal>. Additional arguments to +pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority can be specified as a +keyword-value pair with the keyword "priority". If +<parameter>callback</parameter> returns <literal>FALSE</literal> it is +automatically removed from the list of event sources and will not be called +again.</para> + + </refsect2> + + <refsect2 id="function-glib--timeout-add"> + <title>glib.timeout_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.timeout_add</methodname> + <methodparam><parameter>interval</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>interval</parameter> :</term> + <listitem><simpara>the time between calls to the function, in +milliseconds </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more arguments that will be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event +source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.timeout_add</function>() function sets a +function (specified by <parameter>callback</parameter>) to be called at +regular intervals (specified by <parameter>interval</parameter>, with the +default priority, <literal>glib.PRIORITY_DEFAULT</literal>. Additional +arguments to pass to <parameter>callback</parameter> can be specified after +<parameter>callback</parameter>. The idle priority may be specified as a +keyword-value pair with the keyword "priority".</para> + + <para>The function is called repeatedly until it returns +<literal>FALSE</literal>, at which point the timeout is automatically +destroyed and the function will not be called again. The first call to the +function will be at the end of the first interval. 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 (it does not try to 'catch up' time lost +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> :</term> + <listitem><simpara>the time between calls to the function, in +seconds </simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more arguments that will be passed to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.io_add_watch</methodname> + <methodparam><parameter>fd</parameter></methodparam> + <methodparam><parameter>condition</parameter></methodparam> + <methodparam><parameter>callback</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>fd</parameter> :</term> + <listitem><simpara>a Python file object or an integer file +descriptor ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>condition</parameter> :</term> + <listitem><simpara>a condition mask</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>callback</parameter> :</term> + <listitem><simpara>a function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional arguments to pass to +<parameter>callback</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer ID of the event source</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.io_add_watch</function>() function +arranges for the file (specified by <parameter>fd</parameter>) to be +monitored by the main loop for the specified +<parameter>condition</parameter>. <parameter>fd</parameter> may be a Python +file object or an integer file descriptor. The value of condition is a +combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>glib.IO_IN</literal></term> + <listitem> + <simpara>There is data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_OUT</literal></term> + <listitem> + <simpara>Data can be written (without blocking). </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_PRI</literal></term> + <listitem> + <simpara>There is urgent data to read.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_ERR</literal></term> + <listitem> + <simpara>Error condition.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>glib.IO_HUP</literal></term> + <listitem> + <simpara>Hung up (the connection has been broken, usually for +pipes and sockets).</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para>Additional arguments to pass to <parameter>callback</parameter> +can be specified after <parameter>callback</parameter>. The idle priority +may be specified as a keyword-value pair with the keyword "priority". The +signature of the callback function is:</para> + + <programlisting> + def callback(source, cb_condition, ...) +</programlisting> + + <para>where <parameter>source</parameter> is +<parameter>fd</parameter>, the file descriptor; +<parameter>cb_condition</parameter> is the condition that triggered the +signal; and, <parameter>...</parameter> are the zero or more arguments that +were passed to the <function>glib.io_add_watch</function>() +function.</para> + + <para>If the callback function returns <literal>FALSE</literal> it +will be automatically removed from the list of event sources and will not be +called again. If it returns <literal>TRUE</literal> it will be called again +when the condition is matched.</para> + + </refsect2> + + <refsect2 id="function-glib--source-remove"> + <title>glib.source_remove</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.source_remove</methodname> + <methodparam><parameter>tag</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>tag</parameter> :</term> + <listitem><simpara>an integer ID</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the event source was +removed</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.source_remove</function>() function +removes the event source specified by tag (as returned by the <link +linkend="function-glib--idle-add"><function>glib.idle_add</function>()</link>, +<link +linkend="function-glib--timeout-add"><function>glib.timeout_add</function></link>() +and <link +linkend="function-glib--io-add-watch"><function>glib.io_add_watch</function>()</link> +functions)</para> + + </refsect2> + + <refsect2 id="function-glib--main-context-default"> + <title>glib.main_context_default</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.main_context_default</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the default glib.MainContext +object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>glib.main_context_default</function>() function +returns the default glib.MainContext object.</para> + + </refsect2> + + <refsect2 id="function-glib--markup-escape-text"> + <title>glib.markup_escape_text</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.markup_escape_text</methodname> + <methodparam><parameter>text</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>text</parameter> :</term> + <listitem><simpara>the UTF-8 string to be +escaped</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the escaped text</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>glib.markup_escape_text</function>() function +escapes the string specified by <parameter>text</parameter> so that the +markup parser will parse it verbatim. Less than, greater than, ampersand, +etc. are replaced with the corresponding entities. This function would +typically be used when writing out a file to be parsed with the markup +parser.</para> + + <para>Note that this function doesn't protect whitespace and line +endings from being processed according to the XML rules for normalization of +line endings and attribute values.</para> + + </refsect2> + + <refsect2 id="function-glib--child-watch-add"> + <title>glib.child_watch_add</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.child_watch_add</methodname> + <methodparam><parameter role="keyword">pid</parameter></methodparam> + <methodparam><parameter role="keyword">function</parameter></methodparam> + <methodparam><parameter role="keyword">data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">priority</parameter><initializer>glib.PRIORITY_DEFAULT</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">pid</parameter> :</term> + <listitem><simpara>process id of a child process to watch</simpara></listitem> + </varlistentry> + <varlistentry><term><parameter role="keyword">function</parameter> :</term> + <listitem><simpara>the function to call</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">data</parameter> :</term> + <listitem><simpara>the optional data to pass to +<parameter>function</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">priority</parameter> :</term> + <listitem><simpara>the priority of the idle source - one of the +<xref linkend="glib-priority-constants" +endterm="glib-priority-constants-title"></xref></simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the id of event source.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>glib.child_watch_add</function>() function sets +the function specified by <parameter>function</parameter> to be called with +the user data specified by <parameter>data</parameter> when the child +indicated by <parameter>pid</parameter> exits. The signature for the +callback is:</para> + + <programlisting> +def callback(pid, condition, user_data) +</programlisting> + + <para>where <parameter>pid</parameter> is is the child process id, +<parameter>condition</parameter> is the status information about the child +process and <parameter>user_data</parameter> is <parameter>data</parameter> +PyGTK supports only a single callback per process id.</para> + + </refsect2> + + <refsect2 id="function-glib--spawn-async"> + <title>glib.spawn_async</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.spawn_async</methodname> + <methodparam><parameter role="keyword">argv</parameter></methodparam> + <methodparam><parameter role="keyword">envp</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">working_directory</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">flags</parameter><initializer>0</initializer></methodparam> + <methodparam><parameter role="keyword">child_setup</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">user_data</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_input</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_output</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter role="keyword">standard_error</parameter><initializer>None</initializer></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><parameter role="keyword">argv</parameter> :</term> + <listitem><simpara>a sequence of strings containing the arguments +of the child process</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">envp</parameter> :</term> + <listitem><simpara>the child's environment or +<literal>None</literal> to inherit the parent's +environment.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">working_directory</parameter> :</term> + <listitem><simpara>the child's current working directory, or +<literal>None</literal> to inherit parent's</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">flags</parameter> :</term> + <listitem><simpara>flags from the <xref +linkend="glib-spawn-flag-constants" +endterm="glib-spawn-flag-constants-title"></xref>.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">child_setup</parameter> :</term> + <listitem><simpara>a function to run in the child just before +calling <function>exec</function>()</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">user_data</parameter> :</term> + <listitem><simpara>the user data for the +<parameter>child_setup</parameter> function</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_input</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdin</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_output</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stdout</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">standard_error</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> return the file +descriptor for the child's stderr</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 4-tuple containing the child's process id and +the stdin, stdout and stderr file descriptor integers.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>glib.spawn_async</function>() function executes +a child program asynchronously (your program will not block waiting for the +child to exit). The child program is specified by the only argument that +must be provided, <parameter>argv</parameter>. <parameter>argv</parameter> +should be a sequence of strings, to be passed as the argument vector for the +child. The first string in <parameter>argv</parameter> is of course the name +of the program to execute. By default, the name of the program must be a +full path; the <envar>PATH</envar> shell variable will only be searched if +you pass the <literal>glib.SPAWN_SEARCH_PATH</literal> flag in +<parameter>flags</parameter>. The function returns a 4-tuple containing the +child's process id and the file descriptors for the child's stdin, stdout +and stderr. The stdin, stdout and stderr file descriptors are returned only +ofthe corresponding <parameter>standard_input</parameter>, +<parameter>standard_output</parameter> or +<parameter>standard_error</parameter> params are +<literal>TRUE</literal>.</para> + + <para>On Windows, the low-level child process creation API +(<function>CreateProcess</function>()) doesn't use argument vectors, but a +command line. The C runtime library's <function>spawn*</function>() family +of functions (which <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +eventually calls) paste the argument vector elements into a command line, +and the C runtime startup code does a corresponding reconstruction of an +argument vector from the command line, to be passed to +<function>main</function>(). Complications arise when you have argument +vector elements that contain spaces of double quotes. The +<function>spawn*</function>() functions don't do any quoting or escaping, +but on the other hand the startup code does do unquoting and unescaping in +order to enable receiving arguments with embedded spaces or double +quotes. To work around this asymmetry, the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +function will do quoting and escaping on argument vector elements that need +it before calling the C runtime <function>spawn</function>() +function.</para> + + <para><parameter>envp</parameter> is a sequence of strings, where each + string has the form <literal>KEY=VALUE</literal>. This will become the + child's environment. If <parameter>envp</parameter> is + <parameter>None</parameter> or not specified, the child inherits its + parent's environment.</para> + + <para><parameter>flags</parameter> should be the bitwise +<literal>OR</literal> of the <xref linkend="glib-spawn-flag-constants" +endterm="glib-spawn-flag-constants-title"></xref> you want to affect the +function's behaviour. The <literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal> +flag means that the child will not automatically be reaped; you must use a +GChildWatch source to be notified about the death of the child +process. Eventually you must call g_spawn_close_pid() on the child_pid, in +order to free resources which may be associated with the child process. (On +Unix, using a GChildWatch source is equivalent to calling +<function>waitpid</function>() or handling the <literal>SIGCHLD</literal> +signal manually. On Windows, calling g_spawn_close_pid() is equivalent to +calling <function>CloseHandle</function>() on the process handle +returned).</para> + + <para><literal>glib.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal> means +that the parent's open file descriptors will be inherited by the child; +otherwise all descriptors except stdin/stdout/stderr will be closed before +calling <function>exec</function>() in the +child. <literal>glib.SPAWN_SEARCH_PATH</literal> means that +<parameter>argv</parameter>[0] need not be an absolute path, it will be +looked for in the user's +<envar>PATH</envar>. <literal>glib.SPAWN_STDOUT_TO_DEV_NULL</literal> +means that the child's standard output will be discarded, instead of going +to the same location as the parent's standard output. If you use this flag, +<parameter>standard_output</parameter> must be +<literal>None</literal>. <literal>glib.SPAWN_STDERR_TO_DEV_NULL</literal> +means that the child's standard error will be discarded, instead of going to +the same location as the parent's standard error. If you use this flag, +<parameter>standard_error</parameter> must be +<literal>None</literal>. <literal>glib.SPAWN_CHILD_INHERITS_STDIN</literal> +means that the child will inherit the parent's standard input (by default, +the child's standard input is attached to +<filename>/dev/null</filename>). If you use this flag, +<parameter>standard_input</parameter> must be +<literal>None</literal>. <literal>glib.SPAWN_FILE_AND_ARGV_ZERO</literal> +means that the first element of <parameter>argv</parameter> is the file to +execute, while the remaining elements are the actual argument vector to pass +to the file. Normally the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +function uses <parameter>argv</parameter>[0] as the file to execute, and +passes all of <parameter>argv</parameter> to the child.</para> + + <para><parameter>child_setup</parameter> and +<parameter>user_data</parameter> are a function and user data. On POSIX +platforms, the function is called in the child after GLib has performed all +the setup it plans to perform (including creating pipes, closing file +descriptors, etc.) but before calling <function>exec</function>(). That is, +<parameter>child_setup</parameter> is called just before calling +<function>exec</function>() in the child. Obviously actions taken in this +function will only affect the child, not the parent. On Windows, there is no +separate <function>fork</function>() and <function>exec</function>() +functionality. Child processes are created and run right away with one API +call, +<function>CreateProcess</function>(). <parameter>child_setup</parameter> is +called in the parent process just before creating the child process. You +should carefully consider what you do in <parameter>child_setup</parameter> +if you intend your software to be portable to Windows.</para> + + <para>The returned child process id can be used to send signals to the +child, or to wait for the child if you specified the +<literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal> flag. On Windows, child +pid will be returned only if you specified the +<literal>glib.SPAWN_DO_NOT_REAP_CHILD</literal> flag.</para> + + <para>The caller of the <link +linkend="function-glib--spawn-async"><function>glib.spawn_async</function>()</link> +must close any returned file descriptors when they are no longer in +use.</para> + + <para>If <parameter>standard_input</parameter> is +<literal>None</literal>, the child's standard input is attached to +<filename>/dev/null</filename> unless +<literal>glib.SPAWN_CHILD_INHERITS_STDIN</literal> is set.</para> + + <para>If <parameter>standard_error</parameter> is +<literal>None</literal>, the child's standard error goes to the same +location as the parent's standard error unless +<literal>glib.SPAWN_STDERR_TO_DEV_NULL</literal> is set.</para> + + <para>If <parameter>standard_output</parameter> is +<literal>None</literal>, the child's standard output goes to the same +location as the parent's standard output unless +<literal>glib.SPAWN_STDOUT_TO_DEV_NULL</literal> is set.</para> + + <para>If an error occurs, the glib.GError exception will be +raised.</para> + + </refsect2> + + <refsect2 id="function-glib--get-current-time"> + <title>glib.get_current_time</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_current_time</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the current time as the number of seconds and +microseconds from the epoch.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>glib.get_current_time</function>() function +reurns the current time of day as the number of seconds and microseconds +from the epoch.</para> + + </refsect2> + + <refsect2 id="function-glib--get-user-cache-dir"> + <title>glib.get_user_cache_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_cache_dir</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to user's cache directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns a base directory in which to store non-essential, + cached data specific to particular user.</para> + + <para>On UNIX platforms this is determined using the mechanisms + described in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + Base Directory Specification</ulink>.</para> + </refsect2> + + <refsect2 id="function-glib--get-user-config-dir"> + <title>glib.get_user_config_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_config_dir</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to user's configuration directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns a base directory in which to store user-specific + application configuration information such as user preferences + and settings. </para> + + <para>On UNIX platforms this is determined using the mechanisms + described in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + Base Directory Specification</ulink>.</para> + </refsect2> + + <refsect2 id="function-glib--get-user-data-dir"> + <title>glib.get_user_data_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_data_dir</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to user's data directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns a base directory in which to access application + data such as icons that is customized for a particular + user</para> + + <para>On UNIX platforms this is determined using the mechanisms + described in the + <ulink url="http://www.freedesktop.org/Standards/basedir-spec">XDG + Base Directory Specification</ulink>.</para> + </refsect2> + + <refsect2 id="function-glib--get-user-special-dir"> + <title>glib.get_user_special_dir</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.get_user_special_dir</methodname> + <methodparam><parameter>directory</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>directory</emphasis> :</term> + <listitem> + <simpara> + the logical id of special directory, + see <link linkend="glib-user-directory-constants">User + Directory constants</link> for the list of supported + values + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem> + <simpara> + a strings with a path to the requested directory. + </simpara> + </listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGObject 2.18 and above.</para> + </note> + + <para>Returns the full path of a special directory using its + logical id.</para> + + <para>On Unix this is done using the XDG special user + directories. For compatibility with existing practise, + <link linkend="glib-user-directory-constants">glib.USER_DIRECTORY_DESKTOP</link> + falls back to <literal>$HOME/Desktop</literal> when XDG + special user directories have not been set up.</para> + + <para>Depending on the platform, the user might be able to + change the path of the special directory without requiring the + session to restart; GLib will not reflect any change once the + special directories are loaded.</para> + </refsect2> + + <refsect2 id="function-glib--main-depth"> + <title>glib.main_depth</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.main_depth</methodname> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the depth of the stack of calls to the main +context.</simpara></listitem> + </varlistentry> + </variablelist> + <note> + <para>This function is available in PyGTK 2.8 and above.</para> + </note> + + <para>The <function>main_depth</function>() function returns the depth +of the stack of calls in the main context. That is, when called from the +toplevel, it gives 0. When called from within a callback from the <link +linkend="method-glibmaincontext--iteration"><methodname>glib.MainContext.iteration</methodname>()</link> +method (or the <link +linkend="method-glibmainloop--run"><methodname>glib.MainLoop.run</methodname>()</link> +method, etc.) it returns 1. When called from within a callback to a +recursive call to the <link +linkend="method-glibmaincontext--iteration"><methodname>glib.MainContext.iteration</methodname>()</link> +method), it returns 2. And so forth.</para> + + </refsect2> + + <refsect2 id="function-glib--threads-init"> + <title>glib.threads_init</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.threads_init</methodname> + <methodparam><parameter></parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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 glib 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-glib--signal-accumulator-true-handled"> + <title>glib.signal_accumulator_true_handled</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.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-glib--filename-display-name"> + <title>glib.filename_display_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.filename_display_name</methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>filename</emphasis> :</term> + <listitem><simpara>a pathname in the file name + encoding</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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-glib--filename-display-basename"><function>glib.filename_display_basename</function>()</link> + function, since that allows location-based translation of + filenames.</para> + + </refsect2> + + <refsect2 id="function-glib--filename-display-basename"> + <title>glib.filename_display_basename</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.filename_display_basename</methodname> + <methodparam><parameter>filename</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>filename</emphasis> :</term> + <listitem><simpara>an absolute pathname in the file name + encoding</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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-glib--filename-display-name"><function>glib.filename_display_name</function>()</link> + function if you know the whole path, as it allows translation.</para> + + </refsect2> + + <refsect2 id="function-glib--filename-from-utf8"> + <title>glib.filename_from_utf8</title> + + <programlisting><methodsynopsis language="python"> + <methodname>glib.filename_from_utf8</methodname> + <methodparam><parameter>utf8string</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist role="params"> + <varlistentry> + <term><emphasis>utf8string</emphasis> :</term> + <listitem><simpara>a UTF-8 encoded string.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> diff --git a/docs/reference/pyglib-maincontext.xml b/docs/reference/pyglib-maincontext.xml new file mode 100644 index 0000000..ccb91bb --- /dev/null +++ b/docs/reference/pyglib-maincontext.xml @@ -0,0 +1,152 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-glibmaincontext"> + <refnamediv> + <refname>glib.MainContext</refname> + + <refpurpose>an object representing a set of event sources to be handled +in a <link +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link>.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>glib.MainContext</classname></ooclass> +<constructorsynopsis language="python"> + <methodname><link linkend="constructor-glibmaincontext">glib.MainContext</link></methodname> + </constructorsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-glibmaincontext--iteration">iteration</link></methodname> + <methodparam><parameter>may_block</parameter></methodparam> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-glibmaincontext--pending">pending</link></methodname> + </methodsynopsis> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-glibmaincontext">glib.MainContext</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>A <link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> +represents a set of event sources that can be run in a single thread. File +descriptors (plain files, pipes or sockets) and timeouts are the standard +event sources for <literal>GTK</literal> and <literal>PyGTK</literal> though +others can be added. Each event source is assigned a priority. The default +priority, <literal>glib.PRIORITY_DEFAULT</literal>, is 0. Values less +than 0 denote higher priorities. Values greater than 0 denote lower +priorities. Events from high priority sources are always processed before +events from lower priority sources. Single iterations of a <link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> +can be run with the <link +linkend="method-glibmaincontext--iteration"><methodname>iteration</methodname>()</link> +method.</para> + + </refsect1> + + <refsect1 id="constructor-glibmaincontext"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>glib.MainContext</methodname> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link + linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> + object.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>Creates a new <link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> +object.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-glibmaincontext--iteration"> + <title>glib.MainContext.iteration</title> + + <programlisting><methodsynopsis language="python"> + <methodname>iteration</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>may_block</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> the call may block + waiting for an event.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if events were + dispatched.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>iteration</methodname>() method runs a single +iteration. This involves:</para> + + <itemizedlist> + <listitem> + <simpara>checking to see if any associated event sources are ready +to be processed;</simpara> + </listitem> + <listitem> + <simpara>then if no events sources are ready and +<parameter>may_block</parameter> is <literal>TRUE</literal>, waiting for a +source to become ready;</simpara> + </listitem> + <listitem> + <simpara>and finally, dispatching the highest priority events +sources that are ready</simpara> + </listitem> + </itemizedlist> + + <para>Note that even when <parameter>may_block</parameter> is +<literal>TRUE</literal>, it is still possible for +<methodname>iteration</methodname>() to return <literal>FALSE</literal>, +since the the wait may be interrupted for other reasons than an event source +becoming ready.</para> + + </refsect2> + + <refsect2 id="method-glibmaincontext--pending"> + <title>glib.MainContext.pending</title> + + <programlisting><methodsynopsis language="python"> + <methodname>pending</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if events are + pending.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>pending</methodname>() method checks if any +associated sources have pending events.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pyglib-mainloop.xml b/docs/reference/pyglib-mainloop.xml new file mode 100644 index 0000000..bd12fca --- /dev/null +++ b/docs/reference/pyglib-mainloop.xml @@ -0,0 +1,202 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-glibmainloop"> + <refnamediv> + <refname>glib.MainLoop</refname> + + <refpurpose>an object representing the main event loop of a PyGTK + application.</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>glib.MainLoop</classname></ooclass> +<constructorsynopsis language="python"> + <methodname><link linkend="constructor-glibmainloop">glib.MainLoop</link></methodname> + <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter>is_running</parameter><initializer>0</initializer></methodparam> + </constructorsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-glibmainloop--get-context">get_context</link></methodname> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-glibmainloop--is-running">is_running</link></methodname> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-glibmainloop--quit">quit</link></methodname> + </methodsynopsis> +<methodsynopsis language="python"> + <methodname><link linkend="method-glibmainloop--run">run</link></methodname> + </methodsynopsis> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-glibmainloop">glib.MainLoop</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> +represents a main event loop. A <link +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> +is created with the <link +linkend="constructor-glibmainloop">glib.MainLoop</link>() +constructor. After adding the initial event sources, the <link +linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> +method is called. This continuously checks for new events from each of the +event sources and dispatches them. Finally, the processing of an event from +one of the sources leads to a call to the <link +linkend="method-glibmainloop--quit"><methodname>quit</methodname>()</link> +method to exit the main loop, and the <link +linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> +method returns.</para> + + <para>It is possible to create new instances of <link +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> +recursively. This is often used in <literal>PyGTK</literal> applications +when showing modal dialog boxes. Note that event sources are associated with +a particular <link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>, +and will be checked and dispatched for all main loops associated with that +<link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>.</para> + + <para><literal>PyGTK</literal> contains wrappers of some of these +functions, e.g. the <link +linkend="function-gtk--main"><function>gtk.main</function>()</link>, <link +linkend="function-gtk--main-quit"><function>gtk.main_quit</function>()</link> +and <link +linkend="function-gtk--events-pending"><function>gtk.events_pending</function>()</link> +functions.</para> + + </refsect1> + + <refsect1 id="constructor-glibmainloop"> + <title>Constructor</title> + + <programlisting><constructorsynopsis language="python"> + <methodname>glib.MainLoop</methodname> + <methodparam><parameter>context</parameter><initializer>None</initializer></methodparam> + <methodparam><parameter>is_running</parameter><initializer>None</initializer></methodparam> + </constructorsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>context</parameter> :</term> + <listitem><simpara>a <link + linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> + or <literal>None</literal> to use the default + context.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>is_running</parameter> :</term> + <listitem><simpara>if <literal>TRUE</literal> indicates that the + loop is running. This is not very important since calling the <link + linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> + method will set this to <literal>TRUE</literal> + anyway.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new <link + linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> + object.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>Creates a new <link +linkend="class-glibmainloop"><classname>glib.MainLoop</classname></link> +object.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-glibmainloop--get-context"> + <title>glib.MainLoop.get_context</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_context</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the <link + linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> + the mainloop is associated with</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_context</methodname>() method returns the +<link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link> +that the mainloop was created with.</para> + + </refsect2> + + <refsect2 id="method-glibmainloop--is-running"> + <title>glib.MainLoop.is_running</title> + + <programlisting><methodsynopsis language="python"> + <methodname>is_running</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the mainloop is + currently being run.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>is_running</methodname>() method checks to see +if the mainloop is currently being run via the <link +linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> +method.</para> + + </refsect2> + + <refsect2 id="method-glibmainloop--quit"> + <title>glib.MainLoop.quit</title> + + <programlisting><methodsynopsis language="python"> + <methodname>quit</methodname> + </methodsynopsis></programlisting> + + <para>The <methodname>quit</methodname>() method stops the mainloop +from running. Any subsequent calls to the <link +linkend="method-glibmainloop--run"><methodname>run</methodname>()</link> +method will return immediately.</para> + + </refsect2> + + <refsect2 id="method-glibmainloop--run"> + <title>glib.MainLoop.run</title> + + <programlisting><methodsynopsis language="python"> + <methodname>run</methodname> + </methodsynopsis></programlisting> + + <para>The <methodname>run</methodname>() method runs a mainloop until +the <link +linkend="method-glibmainloop--quit"><methodname>quit</methodname>()</link> +method is called. If this is called for the thread of the loop's <link +linkend="class-glibmaincontext"><classname>glib.MainContext</classname></link>, +it will process events from the loop, otherwise it will simply wait.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-classes.xml b/docs/reference/pygobject-classes.xml new file mode 100644 index 0000000..17f925c --- /dev/null +++ b/docs/reference/pygobject-classes.xml @@ -0,0 +1,17 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<chapter id="gobject-class-reference" + xmlns:xi="http://www.w3.org/2001/XInclude"> + +<title>PyGObject Class Reference</title> + +<!-- GOBJECT CLASSES --> +<xi:include href="pygobject.xml"/> +<xi:include href="pygobject-gboxed.xml"/> +<xi:include href="pygobject-gpointer.xml"/> +<xi:include href="pygobject-ginterface.xml"/> +<xi:include href="pygobject-functions.xml"/> +<xi:include href="pygobject-constants.xml"/> + +</chapter> diff --git a/docs/reference/pygobject-constants.xml b/docs/reference/pygobject-constants.xml new file mode 100644 index 0000000..a8f9711 --- /dev/null +++ b/docs/reference/pygobject-constants.xml @@ -0,0 +1,390 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="gobject-constants"> + <refnamediv> + <refname>gobject Constants</refname> + <refpurpose>the built-in constants of the gobject module</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<xref linkend="gobject-param-constants" endterm="gobject-param-constants-title"></xref> +<xref linkend="gobject-signal-constants" endterm="gobject-signal-constants-title"></xref> +<xref linkend="gobject-type-constants" endterm="gobject-type-constants-title"></xref> +<xref linkend="gobject-version-constants" endterm="gobject-version-constants-title"></xref> +</programlisting> + + </refsect1> + + <refsect1 id="gobject-constants-description"> + <title>Description</title> + + <refsect2 id="gobject-param-constants"> + <title id="gobject-param-constants-title">GObject Param Flag Constants</title> + + <para>The Param Flag constants are a set of bit-flags that specify +certain aspects of parameters that can be configured.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.PARAM_READABLE</literal></term> + <listitem> + <simpara>The parameter is readable</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_WRITABLE</literal></term> + <listitem> + <simpara>The parameter is writable</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_CONSTRUCT</literal></term> + <listitem> + <simpara>The parameter will be set upon object + construction</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_CONSTRUCT_ONLY</literal></term> + <listitem> + <simpara>The parameter will only be set upon object + construction</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.PARAM_LAX_VALIDATION</literal></term> + <listitem> + <simpara>Upon parameter conversion strict validation is not + required</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-signal-constants"> + <title id="gobject-signal-constants-title">GObject Signal Flag Constants</title> + + <para>The Signal Flag constants are a set of bit-flags that specify a +signal's behavior. The overall signal description outlines how especially +the <literal>RUN</literal> flags control the stages of a signal +emission.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_FIRST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the first emission + stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_LAST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the third emission + stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_CLEANUP</literal></term> + <listitem> + <simpara>Invoke the object method handler in the last emission + stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_RECURSE</literal></term> + <listitem> + <simpara>Signals being emitted for an object while currently + being in emission for this very object will not be emitted + recursively, but instead cause the first emission to be + restarted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_DETAILED</literal></term> + <listitem> + <simpara>This signal supports "::detail" appendices to the + signal name upon handler connections and emissions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_ACTION</literal></term> + <listitem> + <simpara>Action signals are signals that may freely be emitted + on alive objects from user code via the <link + linkend="method-gobject--emit"><methodname>gobject.emit</methodname>()</link> + method and friends, without the need of being embedded into + extra code that performs pre or post emission adjustments on the + object. They can also be thought of as object methods which can + be called generically by third-party code.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_HOOKS</literal></term> + <listitem> + <simpara>No emissions hooks are supported for this + signal.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-spawn-flag-constants"> + <title id="gobject-spawn-flag-constants-title">GObject Spawn Flag Constants</title> + + <para>The Spawn Flag constants are a set of bit-flags that can be +passed to the <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +function.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SPAWN_LEAVE_DESCRIPTORS_OPEN</literal></term> + <listitem> + <simpara>the parent's open file descriptors will be inherited by +the child; otherwise all descriptors except stdin/stdout/stderr will be +closed before calling <function>exec</function>() in the child.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_DO_NOT_REAP_CHILD</literal></term> + <listitem> + <simpara>the child will not be automatically reaped; you must +call <function>waitpid</function>() or handle <literal>SIGCHLD</literal> +yourself, or the child will become a zombie.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_SEARCH_PATH</literal></term> + <listitem> + <simpara><parameter>argv</parameter>[0] need not be an absolute +path, it will be looked for in the user's <envar>PATH</envar>.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_STDOUT_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard output will be discarded, instead +of going to the same location as the parent's standard output.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_STDERR_TO_DEV_NULL</literal></term> + <listitem> + <simpara>the child's standard error will be discarded.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_CHILD_INHERITS_STDIN</literal></term> + <listitem> + <simpara>the child will inherit the parent's standard input (by +default, the child's standard input is attached to /dev/null).</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SPAWN_FILE_AND_ARGV_ZERO</literal></term> + <listitem> + <simpara>the first element of <parameter>argv</parameter> is the +file to execute, while the remaining elements are the actual argument vector +to pass to the file. Normally <link +linkend="function-gobject--spawn-async"><function>gobject.spawn_async</function>()</link> +uses <parameter>argv</parameter>[0] as the file to execute, and passes all +of <parameter>argv</parameter> to the child.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-type-constants"> + <title id="gobject-type-constants-title">GObject Built-in Type Constants</title> + + <para>The Built-in Type constants specify the pre-defined types used +by gobject.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.TYPE_INVALID</literal></term> + <listitem> + <simpara>An invalid type, used as error return value in some + functions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_NONE</literal></term> + <listitem> + <simpara>A fundamental type indicating no type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_INTERFACE</literal></term> + <listitem> + <simpara>The fundamental type from which all interfaces are + derived.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_CHAR</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a + character. This maps to a string in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_UCHAR</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an unsigned + character. This maps to a string in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_BOOLEAN</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a True or False + value. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_INT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_UINT</literal></term> + <listitem> + <simpara>he fundamental type corresponding to an unsigned + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_LONG</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a long + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_ULONG</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an unsigned + integer. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_INT64</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an long long + integer. This maps to a long integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_UINT64</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an unsigned long + long integer. This maps to a long integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_ENUM</literal></term> + <listitem> + <simpara>The fundamental type corresponding to an enumeration + type. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_FLAGS</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a flag + type. This maps to an integer in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_FLOAT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a floating point + number. This maps to a float in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_DOUBLE</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a double + floating point number. This maps to a float in Python.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_STRING</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a string.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_POINTER</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a pointer to an + anonymous type. This has no corresponding Python type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_BOXED</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a boxed object + type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_PARAM</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a GParamSpec + type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_OBJECT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a GObject + type.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.TYPE_PYOBJECT</literal></term> + <listitem> + <simpara>The fundamental type corresponding to a Python Object + type.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="gobject-version-constants"> + <title id="gobject-version-constants-title">GObject Version Constants</title> + + <para>The Version constants specify the version of +<literal>GLIB</literal> used by PyGTK as a 3-tuple containing the major, +minor and patch release numbers.</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.glib_version</literal></term> + <listitem> + <simpara>A 3-tuple containing (major, minor, patch) release + numbers.</simpara> + </listitem> + </varlistentry> + </variablelist> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-functions.xml b/docs/reference/pygobject-functions.xml new file mode 100644 index 0000000..7ca3918 --- /dev/null +++ b/docs/reference/pygobject-functions.xml @@ -0,0 +1,889 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="gobject-functions"> + <refnamediv> + <refname>gobject Functions</refname> + <refpurpose>miscellaneous functions</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-name">gobject.type_name</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-from-name">gobject.type_from_name</link></methodname> + <methodparam><parameter>type_name</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-parent">gobject.type_parent</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-is-a">gobject.type_is_a</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>parent_type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-children">gobject.type_children</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-interfaces">gobject.type_interfaces</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--type-register">gobject.type_register</link></methodname> + <methodparam><parameter>class</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-new">gobject.signal_new</link></methodname> + <methodparam><parameter>signal_name</parameter></methodparam> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>return_type</parameter></methodparam> + <methodparam><parameter>param_types</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-list-names">gobject.signal_list_names</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-list-ids">gobject.signal_list_ids</link></methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-name">gobject.signal_name</link></methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-query1">gobject.signal_query</link></methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-query2">gobject.signal_query</link></methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--list-properties">gobject.list_properties</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis><methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--new">gobject.new</link></methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </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> + </programlisting> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para>These functions are part of the <literal>PyGTK</literal> gobject +module but are not directly associated with a specific class.</para> + + <note> + <para> + Many functions that previously were in this namespace got moved to <link + linkend="glib-functions"><literal>glib</literal></link> namespace instead. They + are still available in <literal>gobject</literal> for backward compatibility, but + not documented here. If you miss documentation for some function, be sure to + check <link linkend="glib-functions"><literal>glib</literal></link> first. + </para> + </note> + + </refsect1> + + <refsect1> + <title>Functions</title> + + <refsect2 id="function-gobject--type-name"> + <title>gobject.type_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_name</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_name</function>() function returns +the unique name that is assigned to the specified +<parameter>type</parameter>. <parameter>type</parameter> can be a GObject +type, type ID or instance. This function raises a TypeError exception +if <parameter>type</parameter> isn't a <literal>PyGTK</literal> type.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-from-name"> + <title>gobject.type_from_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_from_name</methodname> + <methodparam><parameter>type_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type_name</parameter> :</term> + <listitem><simpara>a string containing the name of a +type</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the type ID named +<parameter>type_name</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_from_name</function>() function +returns the type ID of the <literal>PyGTK</literal> type with the name +specified by <parameter>type_name</parameter>. This function raises a +RuntimeError exception if no type matches +<parameter>type_name</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-parent"> + <title>gobject.type_parent</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_parent</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the parent type ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_parent</function>() function returns +the direct parent type ID of the specified <parameter>type</parameter>. +<parameter>type</parameter> can be a GObject type, type ID or instance. If +<parameter>type</parameter> has no parent, i.e. is a fundamental type, the +RuntimeError exception is raised. </para> + + </refsect2> + + <refsect2 id="function-gobject--type-is-a"> + <title>gobject.type_is_a</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_is_a</methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>parent_type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>parent_type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if +<parameter>parent_type</parameter> is an ancestor of +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_is_a</function>() function returns +<literal>TRUE</literal> if the specified <parameter>type</parameter> is a +descendant of the type specified by <parameter>parent_type</parameter>. This +function also returns <literal>TRUE</literal> if +<parameter>parent_type</parameter> is an interface and +<parameter>type</parameter> conforms to it.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-children"> + <title>gobject.type_children</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_children</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the child types of +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_children</function>() function +returns a list containing the child types of the specified +<parameter>type</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-interfaces"> + <title>gobject.type_interfaces</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_interfaces</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the interface types supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_interfaces</function>() function +returns a list of the interface types supported by +<parameter>type</parameter>. <parameter>type</parameter> can be a GObject +type, type ID or instance. This function returns a RuntimeError exception if +type is not a valid type or has no interfaces.</para> + + </refsect2> + + <refsect2 id="function-gobject--type-register"> + <title>gobject.type_register</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.type_register</methodname> + <methodparam><parameter>class</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>class</parameter> :</term> + <listitem><simpara>a Python class that is a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.type_register</function>() function +registers the specified Python <parameter>class</parameter> as a PyGTK type. +class must be a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. The function generates a name for the new type.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-new"> + <title>gobject.signal_new</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_new</methodname> + <methodparam><parameter>signal_name</parameter></methodparam> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>flags</parameter></methodparam> + <methodparam><parameter>return_type</parameter></methodparam> + <methodparam><parameter>param_types</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>signal_name</parameter> :</term> + <listitem><simpara>a string containing the name of the +signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>the object type that the signal is associated +with</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>flags</parameter> :</term> + <listitem><simpara>the signal flags</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>return_type</parameter> :</term> + <listitem><simpara>the return type of the signal +handler</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>param_types</parameter> :</term> + <listitem><simpara>the parameter types passed to the signal +handler</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a unique integer signal ID</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.signal_new</function>() function registers +a signal with the specified <parameter>signal_name</parameter> for the +specified object <parameter>type</parameter>. The value of +<parameter>flags</parameter> is a combination of:</para> + + <variablelist> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_FIRST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the first emission +stage. </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_LAST</literal></term> + <listitem> + <simpara>Invoke the object method handler in the third emission +stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_RUN_CLEANUP</literal></term> + <listitem> + <simpara>Invoke the object method handler in the last emission +stage.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_RECURSE</literal></term> + <listitem> + <simpara>Signals being emitted for an object while currently +being in emission for this very object will not be emitted recursively, but +instead cause the first emission to be restarted.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_DETAILED</literal></term> + <listitem> + <simpara>This signal supports "::detail" appendixes to the +signal name upon handler connections and emissions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_ACTION</literal></term> + <listitem> + <simpara>Action signals are signals that may freely be emitted +on alive objects from user code via <link +linkend="method-gobject--emit"><methodname>gobject.emit()</methodname>()</link> +and friends, without the need of being embedded into extra code that +performs pre or post emission adjustments on the object. They can also be +thought of as generically callable object methods.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>gobject.SIGNAL_NO_HOOKS</literal></term> + <listitem> + <simpara> No emissions hooks are supported for this +signal.</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para><parameter>return_type</parameter> is the type of the return +value from a signal handler and may be a gobject type, type ID or instance. +The <parameter>param_types</parameter> parameter is a list of additional +types that are passed to the signal handler. Each parameter type may be +specified as a gobject type, type ID or instance. For example, to add a +signal to the gtk.Window type called "my-signal" that calls a handler with a +gtk.Button widget and an integer value and a return value that is a +boolean, use:</para> + + <programlisting> + gobject.signal_new("my_signal", gtk.Window, gobject.SIGNAL_RUN_LAST, gobject.TYPE_BOOLEAN, (gtk.Button, gobject.TYPE_INT)) +</programlisting> + + </refsect2> + + <refsect2 id="function-gobject--signal-list-names"> + <title>gobject.signal_list_names</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_list_names</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the signal names supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.signal_list_names</function>() function +returns a list of the names of the signals that are supported by the +specified GObject <parameter>type</parameter></para> + + <note> + <para>The type keyword is available in PyGTK 2.6 and above.</para> + </note> + + </refsect2> + + <refsect2 id="function-gobject--signal-list-ids"> + <title>gobject.signal_list_ids</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_list_ids</methodname> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the signal ids supported by +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_list_ids</function>() function +returns a list of the integer ids of the signals that are supported by the +GObject specified by <parameter>type</parameter></para> + + </refsect2> + + <refsect2 id="function-gobject--signal-lookup"> + <title>gobject.signal_lookup</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_lookup</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>the name of a signal for +<parameter>type</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the integer id of a signal supported by +<parameter>type</parameter></simpara> or 0.</listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_lookup</function>() function +returns the id of the signal with the name specified by +<parameter>name</parameter> that is supported by the GObject specified +specified by<parameter>type</parameter>. 0 is returned if the signal is not +found.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-name"> + <title>gobject.signal_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_name</methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">signal_id</parameter> :</term> + <listitem><simpara>an integer signal id</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>the name of the signal or +<literal>None</literal>.</simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_name</function>() function returns +the name of the signal that has the signal id specified by +<parameter>id</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--signal-query1"> + <title>gobject.signal_query</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_query</methodname> + <methodparam><parameter role="keyword">name</parameter></methodparam> + <methodparam><parameter role="keyword">type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">name</parameter> :</term> + <listitem><simpara>the name of a signal for +<parameter>type</parameter></simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter role="keyword">type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 6-tuple containing signal information or +<literal>None</literal></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_query</function>() function returns +a 6-tuple containing information about the signal with the name specified by +<parameter>name</parameter> that is supported by the GObject specified by +<parameter>type</parameter>. If the signal is not found +<literal>None</literal> is returned.</para> + + <para>The signal information 6-tuple contains:</para> + + <itemizedlist> + <listitem> + <simpara>the integer signal id</simpara> + </listitem> + <listitem> + <simpara>the signal name</simpara> + </listitem> + <listitem> + <simpara>the GType that the signal is registered for</simpara> + </listitem> + <listitem> + <simpara>the signal flags (see the <xref +linkend="gobject-signal-constants" +endterm="gobject-signal-constants-title"></xref>)</simpara> + </listitem> + <listitem> + <simpara>the GType of the return from the signal callback +function</simpara> + </listitem> + <listitem> + <simpara>a tuple containing the GTypes of the parameters that are +passed to the signal callback function. Note that these may not correspond +exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara> + </listitem> + </itemizedlist> + + </refsect2> + + <refsect2 id="function-gobject--signal-query2"> + <title>gobject.signal_query</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.signal_query</methodname> + <methodparam><parameter role="keyword">signal_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter role="keyword">signal_id</parameter> :</term> + <listitem><simpara>the integer id of a signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a 6-tuple containing signal information or +<literal>None</literal></simpara></listitem> + </varlistentry> + </variablelist> + + <note> + <para>This method is available in PyGTK 2.6 and above.</para> + </note> + + <para>The <function>gobject.signal_query</function>() function returns +a 6-tuple containing information about the signal with the id specified by +<parameter>signal_id</parameter>. If the signal is not found +<literal>None</literal> is returned.</para> + + <para>The signal information 6-tuple contains:</para> + + <itemizedlist> + <listitem> + <simpara>the integer signal id</simpara> + </listitem> + <listitem> + <simpara>the signal name</simpara> + </listitem> + <listitem> + <simpara>the GType that the signal is registered for</simpara> + </listitem> + <listitem> + <simpara>the signal flags (see the <xref +linkend="gobject-signal-constants" +endterm="gobject-signal-constants-title"></xref>)</simpara> + </listitem> + <listitem> + <simpara>the GType of the return from the signal callback +function</simpara> + </listitem> + <listitem> + <simpara>a tuple containing the GTypes of the parameters that are +passed to the signal callback function. Note that these may not correspond +exactly to the <literal>PyGTK</literal> signal callback parameters.</simpara> + </listitem> + </itemizedlist> + + </refsect2> + + <refsect2 id="function-gobject--list-properties"> + <title>gobject.list_properties</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.list_properties</methodname> + <methodparam><parameter>type</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a list of the properties (as GParam objects) +supported by <parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.list_properties</function>() function +returns a list of the properties (as GParam objects) supported by +<parameter>type</parameter>.</para> + + </refsect2> + + <refsect2 id="function-gobject--new"> + <title>gobject.new</title> + + <programlisting><methodsynopsis language="python"> + <methodname>gobject.new</methodname> + <methodparam><parameter>type</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>type</parameter> :</term> + <listitem><simpara>a GObject type, type ID or +instance</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>zero or more property-value +pairs</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a new object if the specified +<parameter>type</parameter></simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <function>gobject.new</function>() function returns a new +object of the specified <parameter>type</parameter>. type must specify a +type that is a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. A +TypeError exception is raised if <parameter>type</parameter> specifies an +abstract class or a type that is not a descendant of <link +linkend="class-gobject"><classname>gobject.GObject</classname></link>. A set +of property-value pairs may be specified to set the value of the object's +properties.</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> :</term> + <listitem><simpara>a Python GObject instance or + type</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>name</emphasis> :</term> + <listitem><simpara>a signal name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>callback</emphasis> :</term> + <listitem><simpara>a function</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>...</emphasis> :</term> + <listitem><simpara>zero or more extra arguments that will be + passed to callback.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</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> :</term> + <listitem><simpara>a Python GObject instance or + type</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>name</emphasis> :</term> + <listitem><simpara>a signal name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>hook_id</emphasis> :</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> :</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> :</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> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-gboxed.xml b/docs/reference/pygobject-gboxed.xml new file mode 100644 index 0000000..f7f2438 --- /dev/null +++ b/docs/reference/pygobject-gboxed.xml @@ -0,0 +1,68 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectgboxed"> + <refnamediv> + <refname>gobject.GBoxed</refname> + <refpurpose>an object containing an opaque chunk of data</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GBoxed</classname></ooclass> +<methodsynopsis language="python"> + <methodname><link linkend="method-gobjectgboxed--copy">copy</link></methodname> + </methodsynopsis> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectgboxed">gobject.GBoxed</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectgboxed"><classname>gobject.GBoxed</classname></link> +is an abstract base class that encapsulates an opaque chunk of data to +provide an object-oriented interface and a type that is registered with the +<literal>GLIB</literal> type system. A boxed type is registered with +functions that provide for the copying and freeing of the underlying data +structure - this allows PyGTK to encapsulate these as Python objects.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gobjectgboxed--copy"> + <title>gobject.GBoxed.copy</title> + + <programlisting><methodsynopsis language="python"> + <methodname>copy</methodname> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a copy of the <link + linkend="class-gobjectgboxed"><classname>gobject.GBoxed</classname></link> + object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>copy</methodname>() method makes and returns a copy of the boxed object.</para> + + </refsect2> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-ginterface.xml b/docs/reference/pygobject-ginterface.xml new file mode 100644 index 0000000..1b29ddf --- /dev/null +++ b/docs/reference/pygobject-ginterface.xml @@ -0,0 +1,38 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectginterface"> + <refnamediv> + <refname>gobject.GInterface</refname> + + <refpurpose>an object representing a GInterface</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GInterface</classname></ooclass> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectginterface">gobject.GInterface</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectginterface"><classname>gobject.GInterface</classname></link> +is an abstract base class that encapsulates a GInterface.</para> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-gpointer.xml b/docs/reference/pygobject-gpointer.xml new file mode 100644 index 0000000..da16954 --- /dev/null +++ b/docs/reference/pygobject-gpointer.xml @@ -0,0 +1,42 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + +<refentry id="class-gobjectgpointer"> + <refnamediv> + <refname>gobject.GPointer</refname> + + <refpurpose>an object containing a completely opaque chunk of + data</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GPointer</classname></ooclass> +</classsynopsis> + +</refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobjectgpointer">gobject.GPointer</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Description</title> + + <para><link +linkend="class-gobjectgpointer"><classname>gobject.GPointer</classname></link> +is an abstract base class that encapsulates an opaque chunk of data and +registers it with the <literal>GLIB</literal> type system. A pointer type +has no methods and generic ways of copying and freeing the data. It +shouldn't be used in PyGTK.</para> + + </refsect1> + +</refentry> diff --git a/docs/reference/pygobject-introduction.xml b/docs/reference/pygobject-introduction.xml new file mode 100644 index 0000000..fb3e6f2 --- /dev/null +++ b/docs/reference/pygobject-introduction.xml @@ -0,0 +1,222 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> + + <chapter id="pygobject-introduction"> + <title>Introduction</title> + + <para>This document describes many of the <literal>PyGObject</literal> + version 2.12 classes and their methods and associated + functions. Deprecated classes, functions and methods have been + specifically left out of this reference though classes that have become + deprecated since PyGObject 2.0 have been left in but annotated with a + deprecation warning. This document attempts to document as much of the + <literal>PyGObject</literal> <literal>API</literal> as possible but there + are undoubtedly errors and omissions. If you discover any of these please + file a bug report at <ulink + url="http://bugzilla.gnome.org">bugzilla.gnome.org</ulink> for the + <literal>pygobject</literal> project. Specific areas that have not been + documented include:</para> + + <itemizedlist> + <listitem> + <simpara>The GParamSpec class</simpara> + </listitem> + </itemizedlist> + + <para>This reference describes the API for <literal>PyGObject</literal> as + of version 2.11.0+ and assumes that the additional API changes for version + 2.12 will not be significant. There will undoubtedly be changes that are + not reflected in this reference. The differences in the API between + version 2.0 and previous versions are denoted in this reference with a + Note that describes the availability of the object, constructor, method or + function. Any of these that do not have a notation can be assumed to be + available in all versions of PyGObject from 2.0 and up. The source code + must be consulted if this reference and your version of + <literal>PyGObject</literal> seem to differ. You are encouraged to use the + latest version of <literal>PyGObject</literal> that is available. See the + <ulink url="http://www.pygtk.org"><literal>PyGTK</literal> + homepage</ulink> for more information and more resources on how to use + PyGObject as well as help in its development.</para> + + <para> The Reference contains a chapter for each + <literal>PyGObject</literal> module containing the class descriptions. The + class descriptions are arranged alphabetically within the + chapters. Currently there is one module chapter:</para> + + <variablelist> + <varlistentry> + <term>The <literal>gobject</literal> module</term> + <listitem><simpara>The classes that are included in the +<literal>gobject</literal> module of <literal>PyGObject</literal> and are +accessed similar to: gobject.GObject. These classes are the base object +classes that the <literal>gtk</literal> and <literal>gtk.gdk</literal> +module classes are built on.</simpara> + </listitem> + </varlistentry> + </variablelist> + +<!-- + <sect1> + <title>Major Changes since Version 2.11</title> + + <para>The major changes in this document since version 2.11 + include:</para> + + <itemizedlist> + <listitem> + <para></para> + </listitem> + </itemizedlist> + + </sect1> +--> + + <sect1 id="pygobject-reference-format"> + <title>Reference Page Format</title> + + <para>Each <literal>PyGObject</literal> class is described in a reference +page that has a number of sections in a fixed format. Each reference page +will have a subset of the following sections:</para> + + <variablelist> + <varlistentry> + <term>Name</term> + <listitem> + <simpara>The name and a one-line description of the +class.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Synopsis</term> + <listitem> + <simpara>A synopsis of the class and its methods and +optionally a list of associated functions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Ancestry</term> + <listitem> + <simpara>The list of the parent classes of the class. This +section may not be present in all class descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Properties</term> + <listitem> + <simpara>A list of the properties (internal state) +supported by the class. This section may not be present in all classes. The +property descriptions include the name, the access operations (e.g. Read, +Write), and a brief description. Properties are accessed using the <link +linkend="method-gobject--set-property"><methodname>gobject.set_property</methodname>()</link> +and <link +linkend="method-gobject--get-property"><methodname>gobject.get_property</methodname>()</link> +methods that are available to every <literal>PyGObject</literal> object. This +section may not be present in all class descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Attributes</term> + <listitem> + <simpara>A set of internal object state data accessible as Python + attributes (e.g. object.attr). The attribute descriptions include + a name by which the attribute data is accessed, the access mode + (e.g. Read, Write), and a brief description of the attribute. Most + <literal>PyGObject</literal> classes do not support attributes so + this section is not present in most class descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Signal Prototypes</term> + <listitem> + <simpara>A list of the signals supported by the class including + the signal name and a synopsis of the signal handler function + prototype. This section may not be present in all class + descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Description</term> + <listitem><simpara>A description of the class and possibly some of + the methods supported by the class.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Constructor</term> + <listitem> + <simpara>The description of the class object constructor including + the synopsis with brief parameter descriptions and a description + of th use of the constructor. There may be more than one + constructor description if the constructor supports different + parameter lists. This section may not be present in all class + descriptions.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Methods</term> + <listitem> + <simpara>A list of methods supported by the class. Each method + description includes: a synopsis of the method and its parameters + as well as a brief description of each parameter and return value + (if any); and, a description of the use of the method.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Functions</term> + <listitem> + <simpara>A list of related functions. Each function description + includes a synopsis of the function and its parameters and return + value (if any), and a description of the use of the + function.</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Signals</term> + <listitem> + <simpara>A list of signals including a synopsis of the signal + handler prototype function with its parameters and return value + (if any). The signal emission conditions are briefly + described. This section is not present in all class descriptions; + specifically, the <literal>gtk.gdk</literal> classes do not + usually support signals.</simpara> + </listitem> + </varlistentry> + </variablelist> + + <para>The function and method synopsis parameters are displayed in + <emphasis role="bold">bold</emphasis> to denote Python keyword + parameters. Also if the parameter is optional its default value will be + displayed. For example the <link + linkend="function-gobject--signal-lookup"><function>gobject.signal_lookup</function>()</link> + function synopsis is:</para> + + <programlisting> +<methodsynopsis language="python"> + <methodname><link +linkend="function-gobject--signal-lookup">gobject.signal_lookup</link></methodname> + <methodparam><parameter + role="keyword">name</parameter></methodparam> + <methodparam><parameter + role="keyword">type</parameter></methodparam> + </methodsynopsis> +</programlisting> + + <para>The parameters <parameter>name</parameter> and + <parameter>type</parameter> are keyword parameters that can be specified + in a call either by position or keyword (in which case position is not + important). The following calls have the same result:</para> + + <programlisting> + id = gobject.signal_lookup("clicked", gtk.Button) + id = gobject.signal_lookup("clicked", type=gtk.Button) + id = gobject.signal_lookup(name="clicked", type=gtk.Button) + id = gobject.signal_lookup(type=gtk.Button, name="clicked") +</programlisting> + + <para>Parameters that are not keyword parameters are displayed in +<emphasis>italic</emphasis> and must be specified positionally but may also +be optional.</para> + + </sect1> + + </chapter> diff --git a/docs/reference/pygobject-ref.xml b/docs/reference/pygobject-ref.xml new file mode 100644 index 0000000..5fdd80b --- /dev/null +++ b/docs/reference/pygobject-ref.xml @@ -0,0 +1,36 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +<!ENTITY % entities SYSTEM "entities.docbook"> +%entities; +<!ENTITY builddate SYSTEM "builddate.xml"> +]> + +<book id="pygobject-reference" xmlns:xi="http://www.w3.org/2001/XInclude"> + <bookinfo> + <pubdate>&builddate;</pubdate> + <title>PyGObject Reference Manual</title> + <edition>for version &version;</edition> + <releaseinfo>for PyGObject version &version;</releaseinfo> + <abstract> + <para>This reference describes the classes of the python gobject +module.</para> + </abstract> + </bookinfo> + <toc> + </toc> + + <xi:include href="pygobject-introduction.xml"/> + + <xi:include href="pyglib-classes.xml"/> + <xi:include href="pygobject-classes.xml"/> + <xi:include href="pygio-classes.xml"/> + <xi:include href="pygiounix-classes.xml"/> + +<!-- + <index> + <title>Index</title> + </index> +--> + +</book> diff --git a/docs/reference/pygobject.xml b/docs/reference/pygobject.xml new file mode 100644 index 0000000..ac41e47 --- /dev/null +++ b/docs/reference/pygobject.xml @@ -0,0 +1,1016 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<refentry id="class-gobject"> + <refmeta> + <refentrytitle>gobject.GObject</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo>PyGTK Docs</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>gobject.GObject</refname> + <refpurpose>the base class</refpurpose> + </refnamediv> + + <refsect1> + <title>Synopsis</title> + +<classsynopsis language="python"> + <ooclass><classname>gobject.GObject</classname></ooclass> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--get-property">get_property</link></methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--get-properties">get_properties</link></methodname> + <methodparam><parameter>first_property_name</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--set-property">set_property</link></methodname> + <methodparam><parameter>property_name</parameter></methodparam> + <methodparam><parameter>value</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--set-properties">set_properties</link></methodname> + <methodparam><parameter>property_name</parameter> + <initializer>value</initializer></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--freeze-notify">freeze_notify</link></methodname> + <methodparam></methodparam> </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--notify">notify</link></methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--thaw-notify">thaw_notify</link></methodname> + <methodparam></methodparam> </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--get-data">get_data</link></methodname> + <methodparam><parameter>key</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--set-data">set_data</link></methodname> + <methodparam><parameter>key</parameter></methodparam> + <methodparam><parameter>data</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect">connect</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect-after">connect_after</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect-object">connect_object</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--connect-object-after">connect_object_after</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--disconnect">disconnect</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-disconnect">handler_disconnect</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-is-connected">handler_is_connected</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-block">handler_block</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-unblock">handler_unblock</link></methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-block-by-func">handler_block_by_func</link></methodname> + <methodparam><parameter>callable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--handler-unblock-by-func">handler_unblock_by_func</link></methodname> + <methodparam><parameter>callable</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--emit">emit</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--stop-emission">stop_emission</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--emit-stop-by-name">emit_stop_by_name</link></methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis> + <methodsynopsis language="python"> + <methodname><link +linkend="method-gobject--chain">chain</link></methodname> + <methodparam></methodparam> </methodsynopsis> +</classsynopsis> + + </refsect1> + + <refsect1> + <title>Ancestry</title> + +<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> +</synopsis> + + </refsect1> + + <refsect1> + <title>Attributes</title> + + <blockquote role="properties"> + <informaltable pgwide="1" frame="none"> + <tgroup cols="3"> + <?dbhtml cellpadding="5"?> + <colspec column="1" colwidth="1in"/> + <colspec column="2" colwidth="1in"/> + <colspec column="3" colwidth="4in"/> + <tbody> + + <row valign="top"> + <entry>"props"</entry> + <entry>Read/Write</entry> + <entry> + <para>This attribute gives full access to GObject properties as + simple attributes. It can be used to iterate over all the object + properties, and can be used both on class or instance objects.</para> + <para>Examples:</para> + <programlisting> +button = Button() +button_label = button.props.label +button.props.label = 'Click on this fancy button' +for pspec in button.props: + print pspec + print button.get_property(pspec.name) +label_pspec = Button.props.label +button_label = button.get_property(label_pspec.name) + </programlisting> + </entry> + </row> + <row valign="top"> + <entry>"__doc__"</entry> + <entry>Read</entry> + <entry>The documentation for the object type. Uses + "__gdoc__" if no specific documentation set.</entry> + </row> + <row valign="top"> + <entry>"__gdoc__"</entry> + <entry>Read</entry> + <entry>The generated documentation for the underlying GObject + type.</entry> + </row> + <row valign="top"> + <entry>"__gtype__"</entry> + <entry>Read</entry> + <entry>The underlying GObject type.</entry> + </row> + <row valign="top"> + <entry>"__grefcount__"</entry> + <entry>Read</entry> + <entry>The reference count for the underlying GObject.</entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </blockquote> + + </refsect1> + + <refsect1 id="signal-prototypes-gobject"> + <title>gobject.GObject Signal Prototypes</title> + + + <variablelist> + <varlistentry> + <term>"<link linkend="signal-gobject--notify">notify</link>"</term> + <listitem> + <methodsynopsis language="python"><methodname>callback</methodname> + <methodparam><parameter>gobject</parameter></methodparam> + <methodparam><parameter>property_spec</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Description</title> + <para>The <link + linkend="class-gobject"><classname>gobject.GObject</classname></link> + class is the base class providing the common attributes and methods for + the PyGTK classes. The <link + linkend="class-gobject"><classname>gobject.GObject</classname></link> + class is not a user interface widget class.</para> + + <para>The <link + linkend="class-gobject"><classname>gobject.GObject</classname></link> + class provides the signal management methods, the object property access + methods and the object data management methods.</para> + + </refsect1> + + <refsect1> + <title>Methods</title> + + <refsect2 id="method-gobject--get-property"> + <title>gobject.GObject.get_property</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_property</methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>a string containing the property name for the +GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a Python object containing the value of the +property</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_property</methodname>() method returns the +value of the property specified by <parameter>property_name</parameter> or +None if there is no value associated with the property.</para> + <para>The <exceptionname>TypeError</exceptionname> exception is raised +if the property name is not registered with the object class.</para> + + </refsect2> + + <refsect2 id="method-gobject--get-properties"> + <title>gobject.GObject.get_properties</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_properties</methodname> + <methodparam><parameter>first_property_name</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>first_property_name</parameter> :</term> + <listitem><simpara>a string containing the first property name for the +GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional property names +</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a tuple containing the property values +requested</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_properties</methodname>() method returns a tuple containing +the values of the properties requested, or +None if there is no value associated with the property.</para> + <para>The <exceptionname>TypeError</exceptionname> exception is raised +if the property name is not registered with the object class.</para> + + </refsect2> + + <refsect2 id="method-gobject--set-property"> + <title>gobject.GObject.set_property</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_property</methodname> + <methodparam><parameter>property_name</parameter></methodparam> + <methodparam><parameter>value</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>a string containing the property +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a Python object containing the property value +to be set</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>set_property</methodname>() method sets the +property specified by <parameter>property_name</parameter> to the specified +<parameter>value</parameter>.</para> + <para>The <exceptionname>TypeError</exceptionname> exception is raised +if the property name is not registered with the object class or if the value +specified could not be converted to the property type.</para> + + </refsect2> + + <refsect2 id="method-gobject--set-properties"> + <title>gobject.GObject.set_properties</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_properties</methodname> + <methodparam><parameter>property_name</parameter> + <initializer>value</initializer></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>the property name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>value</parameter> :</term> + <listitem><simpara>a Python object containing the property value +to be set</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional property name and value +kwargs</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>set_properties</methodname>() method sets the +property specified by <parameter>property_name</parameter> to the specified +<parameter>value</parameter>, followed by pairs of property name +and value as keyword arguments.</para> + <para>The <exceptionname>TypeError</exceptionname> exception is raised +if the property name is not registered with the object class or if the value +specified could not be converted to the property type.</para> + + </refsect2> + + <refsect2 id="method-gobject--freeze-notify"> + <title>gobject.GObject.freeze_notify</title> + + <programlisting><methodsynopsis language="python"> + <methodname>freeze_notify</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <para>The <methodname>freeze_notify</methodname>() method freezes the +object's property-changed notification queue so that "notify" signals are +blocked until the <methodname>thaw_notify</methodname>() method is +called.</para> + + </refsect2> + + <refsect2 id="method-gobject--notify"> + <title>gobject.GObject.notify</title> + + <programlisting><methodsynopsis language="python"> + <methodname>notify</methodname> + <methodparam><parameter>property_name</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>property_name</parameter> :</term> + <listitem><simpara>a string containing a property +name</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>notify</methodname>() method causes the "notify" +signal for the property specified by <parameter>property_name</parameter> to +be emitted.</para> + + </refsect2> + + <refsect2 id="method-gobject--thaw-notify"> + <title>gobject.GObject.thaw_notify</title> + + <programlisting><methodsynopsis language="python"> + <methodname>thaw_notify</methodname> + <methodparam></methodparam> + </methodsynopsis></programlisting> + + <para>The <methodname>thaw_notify</methodname>() method thaws the +object's property-changed notification queue so that "notify" signals are +emitted.</para> + + </refsect2> + + <refsect2 id="method-gobject--get-data"> + <title>gobject.GObject.get_data</title> + + <programlisting><methodsynopsis language="python"> + <methodname>get_data</methodname> + <methodparam><parameter>key</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>key</parameter> :</term> + <listitem><simpara>a string used as the key</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a Python object containing the associated +data</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>get_data</methodname>() method returns the +Python object associated with the specified <parameter>key</parameter> or +None if there is no data associated with the <parameter>key</parameter> or +if there is no key associated with the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--set-data"> + <title>gobject.GObject.set_data</title> + + <programlisting><methodsynopsis language="python"> + <methodname>set_data</methodname> + <methodparam><parameter>key</parameter></methodparam> + <methodparam><parameter>data</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>key</parameter> :</term> + <listitem><simpara>a string used as a key</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>data</parameter> :</term> + <listitem><simpara>a Python object that is the value to be +associated with the key</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>set_data</methodname>() method associates the +specified Python object (<parameter>data</parameter>) with +<parameter>key</parameter>.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect"> + <title>gobject.GObject.connect</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object.</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional optional +parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect</methodname>() method adds a function or +method (<parameter>handler</parameter>)to the end of the list of signal +handlers for the named <parameter>detailed_signal</parameter> but before the +default class signal handler. An optional set of parameters may be specified +after the <parameter>handler</parameter> parameter. These will all be passed +to the signal handler when invoked.</para> + <para>For example if a function handler was connected to a signal +using:</para> + <programlisting> + handler_id = object.connect("signal_name", handler, arg1, arg2, arg3) +</programlisting> + <para>The handler should be defined as:</para> + <programlisting> + def handler(object, arg1, arg2, arg3): +</programlisting> + <para>A method handler connected to a signal using:</para> + <programlisting> + handler_id = object.connect("signal_name", self.handler, arg1, arg2) +</programlisting> + <para>requires an additional argument when defined:</para> + <programlisting> + def handler(self, object, arg1, arg2) +</programlisting> + <para>A <exceptionname>TypeError</exceptionname> exception is raised +if <parameter>detailed_signal</parameter> identifies a signal name that is +not associated with the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect-after"> + <title>gobject.GObject.connect_after</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect_after</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional optional +parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect_after</methodname>() method is similar +to the <methodname>connect</methodname>() method except that the +<parameter>handler</parameter> is added to the signal handler list after the +default class signal handler. Otherwise the details of +<parameter>handler</parameter> definition and invocation are the +same.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect-object"> + <title>gobject.GObject.connect_object</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect_object</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + <methodparam><parameter>gobject</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>a GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect_object</methodname>() method is the same +as the <methodname>connect</methodname>() method except that the +<parameter>handler</parameter> is invoked with the specified +<parameter>gobject</parameter> in place of the object invoking the +<methodname>connect_object</methodname>() method. For example, a call with a +function handler:</para> + <programlisting> + handler_id = object("signal_name", handler, gobject) +</programlisting> + <para>will cause the <parameter>handler</parameter> to be invoked +as:</para> + <programlisting> + handler(gobject) +</programlisting> + <para>Likewise a method handler will be invoked as:</para> + <programlisting> + self.handler(gobject) +</programlisting> + <para>This can be helpful in invoking PyGTK widget methods that +require no arguments except the widget itself (e.g. +<methodname>widget.destroy</methodname>()) by using the class method as the +handler. For example, a Button "clicked" signal can be set up to invoke the +Window <methodname>destroy</methodname>() method as:</para> + + <programlisting> + handler_id = button.connect_object("clicked", Window.destroy, window) +</programlisting> + + <para>When the button is clicked the handler is invoked as:</para> + + <programlisting> + Window.destroy(window) +</programlisting> + + <para>which is the same as:</para> + + <programlisting> + window.destroy() +</programlisting> + + <para>Additional arguments may be passed to the handler as with the +<methodname>connect</methodname>() method handler invocations.</para> + + </refsect2> + + <refsect2 id="method-gobject--connect-object-after"> + <title>gobject.GObject.connect_object_after</title> + + <programlisting><methodsynopsis language="python"> + <methodname>connect_object_after</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>handler</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>handler</parameter> :</term> + <listitem><simpara>a Python function or method +object</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>a GObject</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>connect_object_after</methodname>() method is +similar to the <methodname>connect_object</methodname>() method except that +the <parameter>handler</parameter> is added to the signal handler list after +the default class signal handler. Otherwise the details of +<parameter>handler</parameter> definition and invocation are the +same.</para> + + </refsect2> + + <refsect2 id="method-gobject--disconnect"> + <title>gobject.GObject.disconnect</title> + + <programlisting><methodsynopsis language="python"> + <methodname>disconnect</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>disconnect</methodname>() method removes the +signal handler with the specified <parameter>handler_id</parameter> from the +list of signal handlers for the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-disconnect"> + <title>gobject.GObject.handler_disconnect</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_disconnect</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_disconnect</methodname>() method removes +the signal handler with the specified <parameter>handler_id</parameter> from +the list of signal handlers for the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-is-connected"> + <title>gobject.GObject.handler_is_connected</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_is_connected</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara><literal>TRUE</literal> if the signal handler +is connected to the object.</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_is_connected</methodname>() method +returns <literal>TRUE</literal> if the signal handler with the specified +<parameter>handler_id</parameter> is connected to the object.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-block"> + <title>gobject.GObject.handler_block</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_block</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_block</methodname>() method blocks the +signal handler with the specified <parameter>handler_id</parameter> from +being invoked until it is unblocked.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-unblock"> + <title>gobject.GObject.handler_unblock</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_unblock</methodname> + <methodparam><parameter>handler_id</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>handler_id</parameter> :</term> + <listitem><simpara>an integer handler +identifier</simpara></listitem> + </varlistentry> + </variablelist> + + </refsect2> + + <refsect2 id="method-gobject--handler-block-by-func"> + <title>gobject.GObject.handler_block_by_func</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_block_by_func</methodname> + <methodparam><parameter>callable</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>callable</parameter> :</term> + <listitem><simpara>a callable python object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_block_by_func</methodname>() method blocks the +all signal handler connected to a specific <parameter>callable</parameter> from +being invoked until the callable is unblocked.</para> + + </refsect2> + + <refsect2 id="method-gobject--handler-unblock-by-func"> + <title>gobject.GObject.handler_unblock_by_func</title> + + <programlisting><methodsynopsis language="python"> + <methodname>handler_unblock_by_func</methodname> + <methodparam><parameter>callback</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>callable</parameter> :</term> + <listitem><simpara>a callable python object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>handler_unblock_by_func</methodname>() method unblocks +all signal handler connected to a specified <parameter>callable</parameter> +thereby allowing it to be invoked when the associated signals are +emitted.</para> + + </refsect2> + + <refsect2 id="method-gobject--emit"> + <title>gobject.GObject.emit</title> + + <programlisting><methodsynopsis language="python"> + <methodname>emit</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a PyObject*</simpara></listitem> + </varlistentry> + </variablelist> + <para>The <methodname>emit</methodname>() method causes the object to +emit the signal specified by <parameter>detailed_signal</parameter>. The +additional parameters must match the number and type of the required signal +handler parameters. In most cases no additional parameters are needed. for +example:</para> + <programlisting> + button.emit("clicked") +</programlisting> + <para>is all that is required to emit the "clicked" signal for a +button. The most common case requiring additional parameters occurs when +emitting an event signal; for example:</para> + <programlisting> + button.emit("button_press_event", event) +</programlisting> + + </refsect2> + + <refsect2 id="method-gobject--stop-emission"> + <title>gobject.GObject.stop_emission</title> + + <programlisting><methodsynopsis language="python"> + <methodname>stop_emission</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>stop_emission</methodname>() method stops the +current emission of the signal specified by +<parameter>detailed_signal</parameter>. Any signal handlers in the list +still to be run will not be invoked.</para> + + </refsect2> + + <refsect2 id="method-gobject--emit-stop-by-name"> + <title>gobject.GObject.emit_stop_by_name</title> + + <programlisting><methodsynopsis language="python"> + <methodname>emit_stop_by_name</methodname> + <methodparam><parameter>detailed_signal</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>detailed_signal</parameter> :</term> + <listitem><simpara>a string containing the signal +name</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The <methodname>emit_stop_by_name</methodname>() method stops +the current emission of the signal specified by +<parameter>detailed_signal</parameter>. Any signal handlers in the list +still to be run will not be invoked.</para> + + </refsect2> + + <refsect2 id="method-gobject--chain"> + <title>gobject.GObject.chain</title> + + <programlisting><methodsynopsis language="python"> + <methodname>chain</methodname> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + <variablelist> + <varlistentry> + <term><parameter>...</parameter> :</term> + <listitem><simpara>additional parameters</simpara></listitem> + </varlistentry> + <varlistentry> + <term><emphasis>Returns</emphasis> :</term> + <listitem><simpara>a Python object</simpara></listitem> + </varlistentry> + </variablelist> + + <para>The chain() method does something.</para> + + </refsect2> + + </refsect1> + + <refsect1> + <title>Signals</title> + + <refsect2 id="signal-gobject--notify"> + <title>The GObject "notify" Signal</title> + + <programlisting><methodsynopsis language="python"> + <methodname>callback</methodname> + <methodparam><parameter>gobject</parameter></methodparam> + <methodparam><parameter>property_spec</parameter></methodparam> + <methodparam><parameter>user_param1</parameter></methodparam> + <methodparam><parameter>...</parameter></methodparam> + </methodsynopsis></programlisting> + + <variablelist> + <varlistentry> + <term><parameter>gobject</parameter> :</term> + <listitem><simpara>the gobject that received the +signal</simpara></listitem> + </varlistentry> + <varlistentry> + <term><parameter>property_spec</parameter> :</term> + <listitem><simpara>the <link linkend="class-gobjectgparamspec"><classname>gobject.GParamSpec</classname></link> of the property that was +changed</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>The "notify" signal is emitted on a gobject when one of its +properties has been changed. Note that getting this signal doesn't guarantee +that the value of the property has actually changed, it may also be emitted +when the setter for the property is called to reinstate the previous +value. For example to be notified of the change of the title of a <link +linkend="class-gtkwindow"><classname>gtk.Window</classname></link> you could +connect to the "notify" signal similar to:</para> + + <programlisting> + window.connect("notify::title", callback) +</programlisting> + + </refsect2> + + </refsect1> + +</refentry> |