diff options
Diffstat (limited to 'docs/reference/pygio-fileenumerator.xml')
| -rw-r--r-- | docs/reference/pygio-fileenumerator.xml | 488 |
1 files changed, 488 insertions, 0 deletions
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> |