path: root/docs/reference/pygtk-gtkfilefilter.xml

<?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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a bitfield of flags indicating the information
that the custom filter function needs.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><parameter>func</parameter>&nbsp;:</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>&nbsp;:</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>&nbsp;:</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>&nbsp;:</term>
	  <listitem><simpara>a 4-tuple containing the information
about a file.</simpara></listitem>
	</varlistentry>
	<varlistentry>
	  <term><emphasis>Returns</emphasis>&nbsp;:</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>