diff options
Diffstat (limited to 'docs/reference/pygtk-gtkfilefilter.xml')
| -rw-r--r-- | docs/reference/pygtk-gtkfilefilter.xml | 530 |
1 files changed, 0 insertions, 530 deletions
diff --git a/docs/reference/pygtk-gtkfilefilter.xml b/docs/reference/pygtk-gtkfilefilter.xml deleted file mode 100644 index a293d713..00000000 --- a/docs/reference/pygtk-gtkfilefilter.xml +++ /dev/null @@ -1,530 +0,0 @@ -<?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-gtkfilefilter"> - <refnamediv> - <refname>gtk.FileFilter</refname> - <refpurpose>a filter for selecting a file subset (new in PyGTK - 2.4)</refpurpose> - </refnamediv> - - <refsect1> - <title>Synopsis</title> - - <classsynopsis language="python"> - <ooclass><classname>gtk.FileFilter</classname></ooclass> - <ooclass><classname><link linkend="class-gtkobject">gtk.Object</link></classname></ooclass> - <constructorsynopsis language="python"> - <methodname><link linkend="constructor-gtkfilefilter">gtk.FileFilter</link></methodname> - <methodparam></methodparam> - </constructorsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--set-name">set_name</link></methodname> - <methodparam><parameter role="keyword">name</parameter></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--get-name">get_name</link></methodname> - <methodparam></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--add-mime-type">add_mime_type</link></methodname> - <methodparam><parameter role="keyword">mime_type</parameter></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--add-pattern">add_pattern</link></methodname> - <methodparam><parameter role="keyword">pattern</parameter></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--add-custom">add_custom</link></methodname> - <methodparam><parameter>needed</parameter></methodparam> - <methodparam><parameter>func</parameter></methodparam> - <methodparam><parameter>data</parameter></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--get-needed">get_needed</link></methodname> - <methodparam></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--filter">filter</link></methodname> - <methodparam><parameter role="keyword">filter_info</parameter></methodparam> - </methodsynopsis> - <methodsynopsis language="python"> - <methodname><link linkend="method-gtkfilefilter--add-pixbuf-formats">add_pixbuf_formats</link></methodname> - <methodparam></methodparam> - </methodsynopsis> - </classsynopsis> - - </refsect1> - - <refsect1> - <title>Ancestry</title> - -<synopsis>+-- <link linkend="class-gobject">gobject.GObject</link> - +-- <link linkend="class-gtkobject">gtk.Object</link> - +-- <link linkend="class-gtkfilefilter">gtk.FileFilter</link> -</synopsis> - - </refsect1> - - <refsect1 id="properties-gtkfilefilter"> - <title>gtk.FileFilter Properties</title> - - <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para> - - </refsect1> - - <refsect1 id="signal-prototypes-gtkfilefilter"> - <title>gtk.FileFilter Signal Prototypes</title> - - <para><link linkend="signal-prototypes-gobject">gobject.GObject Signal Prototypes</link></para> - <para><link linkend="signal-prototypes-gtkobject">gtk.Object Signal Prototypes</link></para> - </refsect1> - - <refsect1> - <title>Description</title> - - <note> - <para>This widget is available in PyGTK 2.4 and above.</para> - </note> - - <para>A <link - linkend="class-gtkfilefilter"><classname>gtk.FileFilter</classname></link> - is an object that filters files based on a set of rules that it - contains. The categories of information that <link - linkend="class-gtkfilefilter"><classname>gtk.FileFilter</classname></link> - uses to accept or reject the file are given by the <xref - linkend="gtk-filefilter-flags-constants" - endterm="gtk-filefilter-flags-constants-title"></xref>:</para> - - <variablelist> - <varlistentry> - <term><literal>gtk.FILE_FILTER_FILENAME</literal></term> - <listitem> - <simpara>The full path name of the file.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gtk.FILE_FILTER_URI</literal></term> - <listitem> - <simpara>The URI of the file.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gtk.FILE_FILTER_DISPLAY_NAME</literal></term> - <listitem> - <simpara>The simple name of the file as displayed in a file -chooser.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gtk.FILE_FILTER_MIME_TYPE</literal></term> - <listitem> - <simpara>The MIME type of the file.</simpara> - </listitem> - </varlistentry> - </variablelist> - - <para>The <link - linkend="method-gtkfilefilter--add-pattern"><methodname>add_pattern</methodname>()</link> - method adds a rule that only uses the display name - (<literal>gtk.FILE_FILTER_DISPLAY_NAME</literal>) for filtering. The - <link - linkend="method-gtkfilefilter--add-mime-type"><methodname>add_mime_type</methodname>()</link> - method adds a rule that only uses the mime type - (<literal>gtk.FILE_FILTER_MIME_TYPE</literal>) for filtering. To use the - file URI (<literal>gtk.FILE_FILTER_URI</literal>) or filename - (<literal>gtk.FILE_FILTER_FILENAME</literal>) you have to create a - custom filter rule using a callback function that is registered with the - <link - linkend="method-gtkfilefilter--add-custom"><methodname>add_custom</methodname>()</link> - method.</para> - - <para>The pattern rule uses file globbing to match the file display - name:</para> - - <itemizedlist> - <listitem> - <simpara>'*' matches any combination of characters e.g.. "a*c" matches - "abc", "a bridge tic", "aaabbbc" and so on.</simpara> - </listitem> - <listitem> - <simpara>'?' matches any single character e.g. "a?c" matches "abc", - aZc" and so on but not "abbc".</simpara> - </listitem> - <listitem> - <simpara>'[' and ']' enclose a set of characters that can be matched; ranges -of characters can be included by separating the start and end with a dash -(e.g. "a-z" include all the lowercase letters). e.g. "a[0-9]c" matches "a3c" -and "a9c" but not "a28c" or "abc".</simpara> - </listitem> - <listitem> - <simpara>'\' escapes the next character to allow "*", "?", "[" and "]" - to be matched literally.</simpara> - </listitem> - </itemizedlist> - - <para>The MIME type requires an exact match (no pattern matching).</para> - - </refsect1> - - <refsect1 id="constructor-gtkfilefilter"> - <title>Constructor</title> - - <programlisting><constructorsynopsis language="python"> - <methodname>gtk.FileFilter</methodname> - <methodparam></methodparam> </constructorsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>a new -<link linkend="class-gtkfilefilter"><classname>gtk.FileFilter</classname></link></simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This constructor is available in PyGTK 2.4 and above.</para> - </note> - - <para>Creates a new <link -linkend="class-gtkfilefilter"><classname>gtk.FileFilter</classname></link> -with no rules added to it. Such a filter doesn't pass any files, so it's not -particularly useful until you add rules with the <link -linkend="method-gtkfilefilter--add-mime-type"><methodname>add_mime_type()</methodname></link>, -<link -linkend="method-gtkfilefilter--add-pattern"><methodname>add_pattern()</methodname></link> -or <link -linkend="method-gtkfilefilter--add-custom"><methodname>add_custom()</methodname></link> -methods. To create a filter that accepts any file, use:</para> - - <programlisting> - filter = gtk.FileFilter() - filter.add_pattern("*") -</programlisting> - - <para></para> - - - </refsect1> - <refsect1> - <title>Methods</title> - - <refsect2 id="method-gtkfilefilter--set-name"> - <title>gtk.FileFilter.set_name</title> - - <programlisting><methodsynopsis language="python"> - <methodname>set_name</methodname> - <methodparam><parameter role="keyword">name</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter role="keyword">name</parameter> :</term> - <listitem><simpara>the human-readable-name for the -filter.</simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>set_name</methodname>() method sets the -human-readable name of the filter to the string in -<parameter>name</parameter>. The string in <parameter>name</parameter> will -be displayed in the file chooser user interface if there is a selectable -list of filters.</para> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--get-name"> - <title>gtk.FileFilter.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 human-readable name of the filter, -or <literal>None</literal>.</simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>get_name</methodname>() method returns the -human-readable name for the filter or <literal>None</literal> if the name -has not been set. See the <link -linkend="method-gtkfilefilter--set-name"><methodname>set_name()</methodname></link> -method.</para> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--add-mime-type"> - <title>gtk.FileFilter.add_mime_type</title> - - <programlisting><methodsynopsis language="python"> - <methodname>add_mime_type</methodname> - <methodparam><parameter role="keyword">mime_type</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter role="keyword">mime_type</parameter> :</term> - <listitem><simpara>the name of a MIME type</simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>add_mime_type</methodname>() method adds a rule -allowing the mime type specified by <parameter>mime_type</parameter> to be -matched. Sets the needs value to -<literal>gtk.FILE_FILTER_MIME_TYPE</literal> (see the <link -linkend="method-gtkfilefilter--get-needed"><methodname>get_needed</methodname>()</link> -method for more information).</para> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--add-pattern"> - <title>gtk.FileFilter.add_pattern</title> - - <programlisting><methodsynopsis language="python"> - <methodname>add_pattern</methodname> - <methodparam><parameter role="keyword">pattern</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter role="keyword">pattern</parameter> :</term> - <listitem><simpara>a shell style glob pattern</simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>add_pattern</methodname>() method adds a rule -allowing the shell style glob pattern specified by -<parameter>pattern</parameter> to filter file names. Sets the needs value to -<literal>gtk.FILE_FILTER_DISPLAY_NAME</literal> (see the <link -linkend="method-gtkfilefilter--get-needed"><methodname>get_needed</methodname>()</link> -method for more information).</para> - - <para>The pattern rule uses file globbing to match the file display -name:</para> - - <itemizedlist> - <listitem> - <simpara>'*' matches any combination of characters e.g.. "a*c" matches - "abc", "a bridge tic", "aaabbbc" and so on.</simpara> - </listitem> - <listitem> - <simpara>'?' matches any single character e.g. "a?c" matches "abc", - aZc" and so on but not "abbc".</simpara> - </listitem> - <listitem> - <simpara>'[' and ']' enclose a set of characters that can be matched; ranges -of characters can be included by separating the start and end with a dash -(e.g. "a-z" include all the lowercase letters). e.g. "a[0-9]c" matches "a3c" -and "a9c" but not "a28c" or "abc".</simpara> - </listitem> - <listitem> - <simpara>'\' escapes the next character to allow "*", "?", "[" and "]" - to be matched literally.</simpara> - </listitem> - </itemizedlist> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--add-custom"> - <title>gtk.FileFilter.add_custom</title> - - <programlisting><methodsynopsis language="python"> - <methodname>add_custom</methodname> - <methodparam><parameter>needed</parameter></methodparam> - <methodparam><parameter>func</parameter></methodparam> - <methodparam><parameter>data</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter>needed</parameter> :</term> - <listitem><simpara>a bitfield of flags indicating the information -that the custom filter function needs.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>func</parameter> :</term> - <listitem><simpara>a callback function; if the function returns -<literal>True</literal>, then the file will be displayed.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><parameter>data</parameter> :</term> - <listitem><simpara>the data to pass to -<parameter>func</parameter></simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>add_custom</methodname>() method adds a rule to -a filter that allows files to be filtered based on a custom callback -function specified by <parameter>func</parameter>. The bitfield -<parameter>needed</parameter> provides information about what sorts of -information that the filter function needs; this allows GTK+ to avoid -retrieving expensive information when it isn't needed by the -filter. <parameter>needed</parameter> is a combination of:</para> - - <variablelist> - <varlistentry> - <term><literal>gtk.FILE_FILTER_FILENAME</literal></term> - <listitem> - <simpara>The full path name of the file.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gtk.FILE_FILTER_URI</literal></term> - <listitem> - <simpara>The URI of the file.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gtk.FILE_FILTER_DISPLAY_NAME</literal></term> - <listitem> - <simpara>The simple name of the file as displayed in a file -chooser.</simpara> - </listitem> - </varlistentry> - <varlistentry> - <term><literal>gtk.FILE_FILTER_MIME_TYPE</literal></term> - <listitem> - <simpara>The MIME type of the file.</simpara> - </listitem> - </varlistentry> - </variablelist> - - <para>The signature of <parameter>func</parameter> is:</para> - - <programlisting> - def filefilterfunction(filter_info, data): -</programlisting> - - <para>where <parameter>filter_info</parameter> is a 4-tuple where each -item is either a string or <literal>None</literal>. The strings correspond -to: the full pathname of the file, the URI of the file, the display name of -the file and the MIME type of the file. <parameter>data</parameter> is the -value passed in as the <parameter>data</parameter> parameter in the -<methodname>add_custom</methodname>() method. Using a custom filter function -is the only way to filter files based on file URIs or full file -pathnames.</para> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--get-needed"> - <title>gtk.FileFilter.get_needed</title> - - <programlisting><methodsynopsis language="python"> - <methodname>get_needed</methodname> - <methodparam></methodparam> </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara>a bitfield of flags indicating the needed fields -when calling <link -linkend="method-gtkfilefilter--filter"><methodname>filter()</methodname></link></simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>get_needed</methodname>() method returns the -information that is needed by the <link -linkend="class-gtkfilefilter"><classname>gtk.FileFilter</classname></link> -to filter the file info using the <link -linkend="method-gtkfilefilter--filter"><methodname>filter()</methodname></link></para> - - <para>This method is not typically used by applications; it is -intended principally for use in the implementation of <link -linkend="class-gtkfilechooser"><classname>gtk.FileChooser</classname></link>.</para> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--filter"> - <title>gtk.FileFilter.filter</title> - - <programlisting><methodsynopsis language="python"> - <methodname>filter</methodname> - <methodparam><parameter role="keyword">filter_info</parameter></methodparam> - </methodsynopsis></programlisting> - <variablelist> - <varlistentry> - <term><parameter role="keyword">filter_info</parameter> :</term> - <listitem><simpara>a 4-tuple containing the information -about a file.</simpara></listitem> - </varlistentry> - <varlistentry> - <term><emphasis>Returns</emphasis> :</term> - <listitem><simpara><literal>True</literal> if the file should be -displayed</simpara></listitem> - </varlistentry> - </variablelist> - - <note> - <para>This method is available in PyGTK 2.4 and above.</para> - </note> - - <para>The <methodname>filter</methodname>() method tests whether a file should be displayed according to the file filter rules. -The 4-tuple <parameter>filter_info</parameter> should include -the fields returned from the <link linkend="method-gtkfilefilter--get-needed"><methodname>get_needed()</methodname></link> method:</para> - - <itemizedlist> - <listitem> - <simpara>the full pathname of the file if needs includes - <literal>gtk.FILE_FILTER_FILENAME</literal></simpara> - </listitem> - <listitem> - <simpara>the URI of the file is needs includes - <literal>gtk.FILE_FILTER_URI</literal></simpara> - </listitem> - <listitem> - <simpara>the display name (without the path) if the file if needs - includes <literal>gtk.FILE_FILTER_DISPLAY_NAME</literal></simpara> - </listitem> - <listitem> - <simpara>the MIME type of the file if needs includes - <literal>gtk.FILE_FILTER_MIME_TYPE</literal></simpara> - </listitem> - </itemizedlist> - - <para>This method will not typically be used by applications; it is -intended principally for use in the implementation of <link -linkend="class-gtkfilechooser"><classname>gtk.FileChooser</classname></link>.</para> - - </refsect2> - - <refsect2 id="method-gtkfilefilter--add-pixbuf-formats"> - <title>gtk.FileFilter.add_pixbuf_formats</title> - - <programlisting><methodsynopsis language="python"> - <methodname>add_pixbuf_formats</methodname> - <methodparam></methodparam> - </methodsynopsis></programlisting> - - <note> - <para>This method is available in PyGTK 2.6 and above.</para> - </note> - - <para>The <methodname>add_pixbuf_formats</methodname>() method adds a - rule allowing image files in the formats supported by <link - linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</para> - - </refsect2> - - </refsect1> - -</refentry> |