// -*- c++ -*-
// Generated by gtkmmproc -- DO NOT MODIFY!
#ifndef _GTKMM_RECENTINFO_H
#define _GTKMM_RECENTINFO_H


#include <glibmm.h>

/* Copyright (C) 2006 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

#include <gdkmm/pixbuf.h>

#include <time.h>


#ifndef DOXYGEN_SHOULD_SKIP_THIS
typedef struct _GtkRecentInfo GtkRecentInfo;
#endif //DOXYGEN_SHOULD_SKIP_THIS

namespace Gtk
{


/** Contains informations found when looking up an entry of the
 * recently used files list.
 *
 * @newin2p10
 *
 * @ingroup RecentFiles
 */
class RecentInfo
{
  public:
#ifndef DOXYGEN_SHOULD_SKIP_THIS
  typedef RecentInfo CppObjectType;
  typedef GtkRecentInfo BaseObjectType;
#endif /* DOXYGEN_SHOULD_SKIP_THIS */


  // For use with Glib::RefPtr<> only.
  void reference()   const;
  void unreference() const;

  ///Provides access to the underlying C instance.
  GtkRecentInfo*       gobj();

  ///Provides access to the underlying C instance.
  const GtkRecentInfo* gobj() const;

  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  GtkRecentInfo* gobj_copy() const;

protected:
  // Do not derive this.  Gtk::RecentInfo can neither be constructed nor deleted.
  RecentInfo();
  void operator delete(void*, size_t);

private:
  // noncopyable
  RecentInfo(const RecentInfo&);
  RecentInfo& operator=(const RecentInfo&);


public:

  bool equal(const RecentInfo& other) const;
  /// Tests whether the RecentInfo is valid.
  operator bool() const;

  
  /** Gets the URI of the resource.
   * @return The URI of the resource.  The returned string is
   * owned by the recent manager, and should not be freed.
   * 
   * @newin2p10.
   */
  Glib::ustring get_uri() const;
  
  /** Gets the name of the resource.  If none has been defined, the basename
   * of the resource is obtained.
   * @return The display name of the resource.  The returned string
   * is owned by the recent manager, and should not be freed.
   * 
   * @newin2p10.
   */
  Glib::ustring get_display_name() const;
  
  /** Gets the (short) description of the resource.
   * @return The description of the resource.  The returned string
   * is owned by the recent manager, and should not be freed.
   * 
   * @newin2p10.
   */
  Glib::ustring get_description() const;
  
  /** Gets the MIME type of the resource.
   * @return The MIME type of the resource.  The returned string
   * is owned by the recent manager, and should not be freed.
   * 
   * @newin2p10.
   */
  Glib::ustring get_mime_type() const;
  
  
  /** Gets the timestamp (seconds from system's Epoch) when the resource
   * was added to the recently used resources list.
   * @return The number of seconds elapsed from system's Epoch when
   * the resource was added to the list, or -1 on failure.
   * 
   * @newin2p10.
   */
  time_t get_added() const;
  
  /** Gets the timestamp (seconds from system's Epoch) when the resource
   * was last modified.
   * @return The number of seconds elapsed from system's Epoch when
   * the resource was last modified, or -1 on failure.
   * 
   * @newin2p10.
   */
  time_t get_modified() const;
  
  /** Gets the timestamp (seconds from system's Epoch) when the resource
   * was last visited.
   * @return The number of seconds elapsed from system's Epoch when
   * the resource was last visited, or -1 on failure.
   * 
   * @newin2p10.
   */
  time_t get_visited() const;
  
  
  /** Gets the value of the "private" flag.  Resources in the recently used
   * list that have this flag set to <tt>true</tt> should only be displayed by the
   * applications that have registered them.
   * @return <tt>true</tt> if the private flag was found, <tt>false</tt> otherwise.
   * 
   * @newin2p10.
   */
  bool get_private_hint() const;

  
  /** Gets the data regarding the application that has registered the resource
   * pointed by @a info.
   * 
   * If the command line contains any escape characters defined inside the
   * storage specification, they will be expanded.
   * @param app_name The name of the application that has registered this item.
   * @param app_exec Return location for the string containing the command line.
   * @param count Return location for the number of times this item was registered.
   * @param time Return location for the timestamp this item was last registered
   * for this application.
   * @return <tt>true</tt> if an application with @a app_name has registered this
   * resource inside the recently used list, or <tt>false</tt> otherwise.  You should
   * free the returned command line using Glib::free().
   * 
   * @newin2p10.
   */
  bool get_application_info(const Glib::ustring& app_name, Glib::StringArrayHandle& app_exec, guint& count, time_t& time) const;
  Glib::StringArrayHandle get_applications() const;
  
  //_WRAP_METHOD(Glib::StringArrayHandle get_applications(unsigned& length) const, gtk_recent_info_get_applications)
  
  /** Gets the name of the last application that have registered the
   * recently used resource represented by @a info.
   * @return An application name.  Use Glib::free() to free it.
   * 
   * @newin2p10.
   */
  Glib::ustring last_application() const;
  
  /** Checks whether an application registered this resource using @a app_name.
   * @param app_name A string containing an application name.
   * @return <tt>true</tt> if an application with name @a app_name was found,
   * <tt>false</tt> otherwise.
   * 
   * @newin2p10.
   */
  bool has_application(const Glib::ustring& app_name) const;
  
  Glib::StringArrayHandle get_groups() const;
  
  //_WRAP_METHOD(Glib::StringArrayHandle get_groups(unsigned& length) const, gtk_recent_info_get_groups)
  
  /** Checks whether @a group_name appears inside the groups registered for the
   * recently used item @a info.
   * @param group_name Name of a group.
   * @return <tt>true</tt> if the group was found.
   * 
   * @newin2p10.
   */
  bool has_group(const Glib::ustring& group) const;
  
  
  /** Retrieves the icon of size @a size associated to the resource MIME type.
   * @param size The size of the icon in pixels.
   * @return A Gdk::Pixbuf containing the icon, or <tt>0</tt>. Use
   * Glib::object_unref() when finished using the icon.
   * 
   * @newin2p10.
   */
  Glib::RefPtr<Gdk::Pixbuf> get_icon(int size);
  
  /** Retrieves the icon of size @a size associated to the resource MIME type.
   * @param size The size of the icon in pixels.
   * @return A Gdk::Pixbuf containing the icon, or <tt>0</tt>. Use
   * Glib::object_unref() when finished using the icon.
   * 
   * @newin2p10.
   */
  Glib::RefPtr<const Gdk::Pixbuf> get_icon(int size) const;
  
  
  /** 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".
   * @return A newly-allocated string in UTF-8 encoding; free it with
   * Glib::free().
   * 
   * @newin2p10.
   */
  Glib::ustring get_short_name() const;
  
  /** Gets a displayable version of the resource's URI.  If the resource
   * is local, it returns a local path; if the resource is not local,
   * it returns the UTF-8 encoded content of gtk_recent_info_get_uri().
   * @return A newly allocated UTF-8 string containing the
   * resource's URI or <tt>0</tt>. Use Glib::free() when done using it.
   * 
   * @newin2p10.
   */
  Glib::ustring get_uri_display() const;
  
  
  /** Gets the number of days elapsed since the last update of the resource
   * pointed by @a info.
   * @return A positive integer containing the number of days elapsed
   * since the time this resource was last modified.  
   * 
   * @newin2p10.
   */
  int get_age() const;
  
  /** Checks whether the resource is local or not by looking at the
   * scheme of its URI.
   * @return <tt>true</tt> if the resource is local.
   * 
   * @newin2p10.
   */
  bool is_local() const;
  
  /** Checks whether the resource pointed by @a info still exists.  At
   * the moment this check is done only on resources pointing to local files.
   * @return <tt>true</tt> if the resource exists
   * 
   * @newin2p10.
   */
  bool exists() const;

  
  //_WRAP_METHOD(bool match(const RecentInfo& b) const, gtk_recent_info_match)


};


#ifndef DOXYGEN_SHOULD_SKIP_THIS

struct RecentInfoTraits
{
  typedef Glib::RefPtr<RecentInfo> CppType;
  typedef const GtkRecentInfo* CType;
  typedef GtkRecentInfo* CTypeNonConst;

  static CType to_c_type(const CppType& obj) { return Glib::unwrap(obj); }
  static CType to_c_type(const CType& obj) { return obj; }
  static CppType to_cpp_type(const CType& obj); //Implemented in the .cpp file
  static void release_c_type(const CType& /* obj */) { /* gtk_recent_info_unref(const_cast<CTypeNonConst>(obj)); */}
};
#endif

//TODO: We normally put these inside the class:

/** @relates Gtk::RecentInfo */
inline bool operator==(const RecentInfo& lhs, const RecentInfo& rhs)
  { return lhs.equal(rhs); }

/** @relates Gtk::RecentInfo */
inline bool operator!=(const RecentInfo& lhs, const RecentInfo& rhs)
  { return !lhs.equal(rhs); }

} // namespace Gtk

namespace Glib
{

// This is needed so Glib::RefPtr<Gtk::RecentInfo> can be used with
// Glib::Value and Gtk::TreeModelColumn:
template<>
class Value<Glib::RefPtr<Gtk::RecentInfo> >: public ValueBase_Boxed
{
public:
  typedef Glib::RefPtr<Gtk::RecentInfo> CppType;
  typedef GtkRecentInfo* CType;

  static GType value_type();

  void set(const CppType& data);
  CppType get() const;
};

} // namespace Glib


namespace Glib
{

  /** A Glib::wrap() method for this object.
   * 
   * @param object The C instance.
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
   * @result A C++ instance that wraps this C instance.
   *
   * @relates Gtk::RecentInfo
   */
  Glib::RefPtr<Gtk::RecentInfo> wrap(GtkRecentInfo* object, bool take_copy = false);

} // namespace Glib


#endif /* _GTKMM_RECENTINFO_H */

