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

  <refnamediv>
    <refname>gtk.RecentInfo</refname>
      <refpurpose>information found when looking up an entry of the recently
      used files list. (new in PyGTK 2.10)</refpurpose>
  </refnamediv>

  <refsect1>
    <title>Synopsis</title>

    <classsynopsis language="python">
      <ooclass><classname>gtk.RecentInfo</classname></ooclass>
      <ooclass><classname>gobject.GBoxed</classname></ooclass>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-uri">get_uri</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-display-name">get_display_name</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-description">get_description</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-mime-type">get_mime_type</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-added">get_added</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-modified">get_modified</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-visited">get_visited</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-private-hint">get_private_hint</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-application-info">get_application_info</link></methodname>
        <methodparam><parameter role="keyword">app_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-applications">get_applications</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--last-application">last_application</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--has-application">has_application</link></methodname>
        <methodparam><parameter role="keyword">app_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-groups">get_groups</link></methodname>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--has-group">has_group</link></methodname>
        <methodparam><parameter role="keyword">group_name</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-icon">get_icon</link></methodname>
        <methodparam><parameter role="keyword">size</parameter></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-short-name">get_short_name</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-uri-display">get_uri_display</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--get-age">get_age</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--is-local">is_local</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--exists">exists</link></methodname>
        <methodparam></methodparam>
      </methodsynopsis>
      <methodsynopsis language="python">
        <methodname><link linkend="method-gtkrecentinfo--match">match</link></methodname>
        <methodparam><parameter role="keyword">info_b</parameter></methodparam>
      </methodsynopsis>
</classsynopsis>

  </refsect1>

  <refsect1>
    <title>Description</title>

    <para>A <link
    linkend="class-gtkrecentinfo"><classname>gtk.RecentInfo</classname></link>
    contains the information about an entry in a <link
    linkend="class-gtkrecentmanager"><classname>gtk.RecentManager</classname></link>.</para>

  </refsect1>

  <refsect1>
    <title>Methods</title>

    <refsect2 id="method-gtkrecentinfo--get-uri">
      <title>gtk.RecentInfo.get_uri</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_uri</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the URI of the resource.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the URI of the resource.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-display-name">
      <title>gtk.RecentInfo.get_display_name</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_display_name</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the display name of the
          resource.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the name of the resource. If none has been defined, the
      basename of the resource is obtained.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-description">
      <title>gtk.RecentInfo.get_description</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_description</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the description of the
          resource.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the (short) description of the resource.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-mime-type">
      <title>gtk.RecentInfo.get_mime_type</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_mime_type</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the MIME type of the
          resource.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the MIME type of the resource.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-added">
      <title>gtk.RecentInfo.get_added</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_added</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the number of seconds elapsed from system's
          Epoch when the resource was added to the list, or -1 on
          failure.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the timestamp (seconds from system's Epoch) when the
      resource was added to the recently used resources list.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-modified">
      <title>gtk.RecentInfo.get_modified</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_modified</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the number of seconds elapsed from system's
          Epoch when the resource was last modified, or -1 on
          failure.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the timestamp (seconds from system's Epoch) when the
      resource was last modified.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-visited">
      <title>gtk.RecentInfo.get_visited</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_visited</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the number of seconds elapsed from system's
          Epoch when the resource was last visited, or -1 on
          failure.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the timestamp (seconds from system's Epoch) when the
      resource was last visited.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-private-hint">
      <title>gtk.RecentInfo.get_private_hint</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_private_hint</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the private flag was
          found.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the value of the "private" flag.  Resources in the
      recently used list that have this flag set to <literal>True</literal>
      should only be displayed by the applications that have registered
      them.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-application-info">
      <title>gtk.RecentInfo.get_application_info</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_application_info</methodname>
        <methodparam><parameter role="keyword">app_name</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">app_name</parameter>&nbsp;:</term>
          <listitem><simpara>the name of the application that has registered
          this item</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a 3-tuple (containing the command line, the
          number of times this item was registered and the timestamp this
          item was last registered for this application) if an application
          named <parameter>app_name</parameter> has registered this resource
          inside the recently used list, or <literal>None</literal>
          otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns a 3-tuple containg the data regarding the application
      that has registered this resource. The 3-tuple contains the command
      line, the number of times this item was registered and the timestamp
      this item was last registered for this application</para>
      
      <para>If the command line contains any escape characters defined
      inside the storage specification, they will be expanded.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-applications">
      <title>gtk.RecentInfo.get_applications</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_applications</methodname>
        <methodparam><parameter role="keyword">length</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a list of application name
          strings.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the list of applications that have registered this
      resource.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--last-application">
      <title>gtk.RecentInfo.last_application</title>

      <programlisting><methodsynopsis language="python">
        <methodname>last_application</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&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>Returns the name of the last application that has registered the
      recently used resource.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--has-application">
      <title>gtk.RecentInfo.has_application</title>

      <programlisting><methodsynopsis language="python">
        <methodname>has_application</methodname>
        <methodparam><parameter role="keyword">app_name</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">app_name</parameter>&nbsp;:</term>
          <listitem><simpara>a string containing an application
          name</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if an application with
          the name <parameter>app_name</parameter> was found,
          <literal>False</literal> otherwise.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Checks whether an application registered this resource using
      <parameter>app_name</parameter>.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-groups">
      <title>gtk.RecentInfo.get_groups</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_groups</methodname>
        <methodparam><parameter role="keyword">length</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a list of group names.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns a list containing the names of all groups registered
      for the recently used item.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--has-group">
      <title>gtk.RecentInfo.has_group</title>

      <programlisting><methodsynopsis language="python">
        <methodname>has_group</methodname>
        <methodparam><parameter role="keyword">group_name</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">group_name</parameter>&nbsp;:</term>
          <listitem><simpara>the name of a group</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the group was
          found.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Checks whether <parameter>group_name</parameter> appears inside
      the groups registered for the recently used item.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-icon">
      <title>gtk.RecentInfo.get_icon</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_icon</methodname>
        <methodparam><parameter role="keyword">size</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">size</parameter>&nbsp;:</term>
          <listitem><simpara>the size of the icon in
          pixels</simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gdkpixbuf"><classname>gtk.gdk.Pixbuf</classname></link>
          containing the icon, or
          <literal>None</literal>.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Retrieves the icon of size <parameter>size</parameter>
      associated to the resource MIME type.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-short-name">
      <title>gtk.RecentInfo.get_short_name</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_short_name</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>the short name as a UTF-8 string</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Computes a valid UTF-8 string that can be used as the name of
      the item in a menu or list.  For example, calling this function on an
      item that refers to "file:///foo/bar.txt" will yield "bar.txt".</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-uri-display">
      <title>gtk.RecentInfo.get_uri_display</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_uri_display</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a UTF-8 string containing the resource's URI or
          <literal>None</literal></simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Gets a displayable version of the resource's URI.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--get-age">
      <title>gtk.RecentInfo.get_age</title>

      <programlisting><methodsynopsis language="python">
        <methodname>get_age</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara>a positive integer containing the number of
          days elapsed since the time this resource was last
          modified.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Returns the number of days elapsed since the last update of the
      resource.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--is-local">
      <title>gtk.RecentInfo.is_local</title>

      <programlisting><methodsynopsis language="python">
        <methodname>is_local</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the resource is
          local.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Checks whether the resource is local or not by looking at the
      scheme of its URI.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--exists">
      <title>gtk.RecentInfo.exists</title>

      <programlisting><methodsynopsis language="python">
        <methodname>exists</methodname>
        <methodparam></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if the resource
          exists</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Checks whether the resource still exists. At the moment this
      check is done only on resources pointing to local files.</para>

    </refsect2>

    <refsect2 id="method-gtkrecentinfo--match">
      <title>gtk.RecentInfo.match</title>

      <programlisting><methodsynopsis language="python">
        <methodname>match</methodname>
        <methodparam><parameter role="keyword">info_b</parameter></methodparam>
      </methodsynopsis></programlisting>

      <variablelist>
        <varlistentry>
          <term><parameter role="keyword">info_b</parameter>&nbsp;:</term>
          <listitem><simpara>a <link
          linkend="class-gtkrecentinfo"><classname>gtk.RecentInfo</classname></link></simpara></listitem>
        </varlistentry>
        <varlistentry>
          <term><emphasis>Returns</emphasis>&nbsp;:</term>
          <listitem><simpara><literal>True</literal> if
          <parameter>info_b</parameter> matches this recent
          info.</simpara></listitem>
        </varlistentry>
      </variablelist>

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

      <para>Checks if <parameter>info_b</parameter> matches this recent
      info.</para>

    </refsect2>

  </refsect1>

</refentry>