path: root/docs/reference/pygtk-gtkrecentfilter.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-gtkrecentfilter">

  <refnamediv>
    <refname>gtk.RecentFilter</refname>
      <refpurpose>A filter for selecting a subset of recently used files
      (new in PyGTK 2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.RecentFilter</classname></ooclass>
      <ooclass><classname><link linkend="class-gtkobject">gtk.Object</link></classname></ooclass>
      <constructorsynopsis language="python">
        <methodname><link linkend="constructor-gtkrecentfilter">gtk.RecentFilter</link></methodname>
        <methodparam></methodparam>
      </constructorsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--set-name">set_name</link></methodname>
        <methodparam><parameter role="keyword">name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--get-name">get_name</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-mime-type">add_mime_type</link></methodname>
        <methodparam><parameter role="keyword">mime_type</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-pattern">add_pattern</link></methodname>
        <methodparam><parameter role="keyword">pattern</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-pixbuf-formats">add_pixbuf_formats</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-application">add_application</link></methodname>
        <methodparam><parameter role="keyword">application</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-group">add_group</link></methodname>
        <methodparam><parameter role="keyword">group</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-age">add_age</link></methodname>
        <methodparam><parameter role="keyword">days</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--add-custom">add_custom</link></methodname>
        <methodparam><parameter role="keyword">needed</parameter></methodparam>
        <methodparam><parameter role="keyword">func</parameter></methodparam>
        <methodparam><parameter role="keyword">data</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--get-needed">get_needed</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentfilter--filter">filter</link></methodname>
        <methodparam><parameter role="keyword">filter_info</parameter></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-gtkrecentfilter">gtk.RecentFilter</link>
</synopsis>

  </refsect1>

  <refsect1 id="properties-gtkrecentfilter">
    <title>gtk.RecentFilter Properties</title>

    <para><link linkend="properties-gtkobject">gtk.Object Properties</link></para>

  </refsect1>

  <refsect1 id="signal-prototypes-gtkrecentfilter">
    <title>gtk.RecentFilter 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>

    <para>A <link
    linkend="class-gtkrecentfilter"><classname>gtk.RecentFilter</classname></link>
    can be used to restrict the files being shown in a <link
    linkend="class-gtkrecentchooser"><classname>gtk.RecentChooser</classname></link>.
    Files can be filtered based on their name (with the <link
    linkend="method-gtkrecentfilter--add-pattern"><methodname>gtk.RecentFilter.add_pattern()</methodname></link>
    method), on their mime type (with the <link
    linkend="method-gtkfilefilter--add-mime-type"><methodname>gtk.FileFilter.add_mime_type()</methodname></link>
    method), on the application that has registered them (with the <link
    linkend="method-gtkrecentfilter--add-application"><methodname>gtk.RecentFilter.add_application()</methodname></link>
    method), or by a custom filter function (with the <link
    linkend="method-gtkrecentfilter--add-custom"><methodname>gtk.RecentFilter.add_custom()</methodname></link>
    method).</para>

    <para>Filtering by mime type handles aliasing and subclassing of mime
    types; e.g. a filter for "text/plain" also matches a file with mime type
    "application/rtf", since "application/rtf" is a subclass of
    "text/plain".  Note that <link
    linkend="class-gtkrecentfilter"><classname>gtk.RecentFilter</classname></link>
    allows wildcards for the subtype of a mime type, so you can e.g. filter
    for "image/*".</para>

    <para>Normally, filters are used by adding them to a <link
    linkend="class-gtkrecentchooser"><classname>gtk.RecentChooser</classname></link>,
    see the <link
    linkend="method-gtkrecentchooser--add-filter"><methodname>gtk.RecentChooser.add_filter()</methodname></link>
    method, but it is also possible to manually use a filter on a file with
    the <link
    linkend="method-gtkrecentfilter--filter"><methodname>gtk.RecentFilter.filter()</methodname></link>
    method.</para>

    <para>Recently used files are supported since GTK+ 2.10.</para>

  </refsect1>

  <refsect1>
    <title>Constructor</title>

    <refsect2 id="constructor-gtkrecentfilter">
      <title>gtk.RecentFilter</title>

      <programlisting><constructorsynopsis language="python">
        <methodname>gtk.RecentFilter</methodname>
        <methodparam></methodparam>
      </constructorsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a new <link
          linkend="class-gtkrecentfilter"><classname>gtk.RecentFilter</classname></link></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This constructor is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Creates a new <link
      linkend="class-gtkrecentfilter"><classname>gtk.RecentFilter</classname></link>
      with no rules added to it.  Such a filter does not accept any recently
      used resources, so is not particularly useful until you add rules with
      the <link
      linkend="method-gtkrecentfilter--add-pattern"><methodname>gtk.RecentFilter.add_pattern()</methodname></link>,
      <link
      linkend="method-gtkrecentfilter--add-mime-type"><methodname>gtk.RecentFilter.add_mime_type()</methodname></link>,
      <link
      linkend="method-gtkrecentfilter--add-application"><methodname>gtk.RecentFilter.add_application()</methodname></link>,
      <link
      linkend="method-gtkrecentfilter--add-age"><methodname>gtk.RecentFilter.add_age()</methodname></link>
      methods.  To create a filter that accepts any recently used resource,
      use:</para>
      
            <para><informalexample><programlisting>
      filter = gtk.RecentFilter()
      filter.add_pattern("*")
      </programlisting></informalexample></para>

    </refsect2>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkrecentfilter--set-name">
      <title>gtk.RecentFilter.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</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Sets the human-readable name of the filter; this is the string
      that will be displayed in the recently used resources selector user
      interface if there is a selectable list of filters.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--get-name">
      <title>gtk.RecentFilter.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 name of the filter, or
          <literal>None</literal>.</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Returns the human-readable name for the filter.  See the <link
      linkend="method-gtkrecentfilter--set-name"><methodname>gtk.RecentFilter.set_name()</methodname></link>
      method.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-mime-type">
      <title>gtk.RecentFilter.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>a MIME type</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Adds a rule that filters resources based on their registered
      MIME type.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-pattern">
      <title>gtk.RecentFilter.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 file pattern</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Adds a rule that filters resources based on a pattern matching
      their display name.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-pixbuf-formats">
      <title>gtk.RecentFilter.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.10 and above.</para>
      </note>

      <para>Adds a rule that filters image files based on the formats
      supported by <link
      linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-application">
      <title>gtk.RecentFilter.add_application</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_application</methodname>
        <methodparam><parameter role="keyword">application</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">application</parameter>&nbsp;:</term>
          <listitem><simpara>an application name</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Adds a rule that filters resources based on the name of the
      application that has registered them.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-group">
      <title>gtk.RecentFilter.add_group</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_group</methodname>
        <methodparam><parameter role="keyword">group</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">group</parameter>&nbsp;:</term>
          <listitem><simpara>a group name</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Adds a rule that filters resources based on the name of the
      group to which they belong</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-age">
      <title>gtk.RecentFilter.add_age</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_age</methodname>
        <methodparam><parameter role="keyword">days</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">days</parameter>&nbsp;:</term>
          <listitem><simpara>number of days</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Adds a rule that filters resources based on their age -
      that is, the number of days elapsed since they were last
      modified.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--add-custom">
      <title>gtk.RecentFilter.add_custom</title>

      <programlisting><methodsynopsis language="python">
        <methodname>add_custom</methodname>
        <methodparam><parameter role="keyword">needed</parameter></methodparam>
        <methodparam><parameter role="keyword">func</parameter></methodparam>
        <methodparam><parameter role="keyword">data</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">needed</parameter>&nbsp;:</term>
          <listitem><simpara>a combination of the <xref
          linkend="gtk-recent-filter-flags-constants"
          endterm="gtk-recent-filter-flags-constants-title"></xref>
          indicating the information that the custom filter function
          needs.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">func</parameter>&nbsp;:</term>
          <listitem><simpara>callback function; if the function returns <literal>True</literal>, then
  the file will be displayed.</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><parameter role="keyword">data</parameter>&nbsp;:</term>
          <listitem><simpara>data to pass to <parameter>func</parameter></simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Adds a rule to a filter that filters resources based on a custom
      callback function. <parameter>needed</parameter> is a combination of
      the <xref linkend="gtk-recent-filter-flags-constants"
      endterm="gtk-recent-filter-flags-constants-title"></xref> which
      provides information about what sorts of information that the filter
      function needs; this allows PyGTK to avoid retrieving expensive
      information when it isn't needed by the filter.</para>

      <para>The signature of the filter function is:</para>

      <programlisting>
  def func(filterinfo, user_data):
      </programlisting>

      <para>where <parameter>filterinfo</parameter> is a dict containing the
      info requested by <parameter>needed</parameter> as key-value pairs and
      <parameter>user_data</parameter> is <parameter>data</parameter>. The
      possible <parameter>filterinfo</parameter> keys are: "uri",
      "display_name", "mime_type", "applications", "age" and
      "groups".</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--get-needed">
      <title>gtk.RecentFilter.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 combination of the <xref
          linkend="gtk-recent-filter-flags-constants"
          endterm="gtk-recent-filter-flags-constants-title"></xref>
          indicating what fields are used for filtering when calling the
          <link
          linkend="method-gtkrecentfilter--filter"><methodname>gtk.RecentFilter.filter()</methodname></link>
          method</simpara></listitem>
        </varlistentry>
      </variablelist>

      <note>
        <para>This method is available in PyGTK 2.10 and above.</para>
      </note>

      <para>Returns a combination of the <xref
      linkend="gtk-recent-filter-flags-constants"
      endterm="gtk-recent-filter-flags-constants-title"></xref> indicating
      what fields are used for filtering.</para>
      
      <para>This method will not typically be used by applications; it is
      intended principally for use in the implementation of <link
      linkend="class-gtkrecentchooser"><classname>gtk.RecentChooser</classname></link>.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentfilter--filter">
      <title>gtk.RecentFilter.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 filter info dict containing information about
          a recently used resource</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.10 and above.</para>
      </note>

      <para>Returns <literal>True</literal> if a file should be displayed.
      <parameter>filter_info</parameter> is a dict that should include the
      key-value pairs as specified by the return flags from the <link
      linkend="method-gtkrecentfilter--get-needed"><methodname>gtk.RecentFilter.get_needed()</methodname></link>
      method. The possible <parameter>filter_info</parameter> keys are:
      "uri", "display_name", "mime_type", "applications", "age" and
      "groups".</para>
      
      <para>This method will not typically be used by applications; it is
      intended principally for use in the implementation of <link
      linkend="class-gtkrecentchooser"><classname>gtk.RecentChooser</classname></link>.</para>

    </refsect2>

  </refsect1>

</refentry>