/* 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, see <https://www.gnu.org/licenses/>.
 */

_CONFIGINCLUDE(gtkmmconfig.h)

#include <vector>
#include <gdkmm/pixbuf.h>
#include <gtkmm/recentinfo.h>
#include <glibmm/object.h>

_DEFS(gtkmm,gtk)
_PINCLUDE(glibmm/private/object_p.h)

namespace Gtk
{

/** Exception class for Gtk::RecentManager errors.
 */
_WRAP_GERROR(RecentManagerError, GtkRecentManagerError, GTK_RECENT_MANAGER_ERROR, decl_prefix GTKMM_API)

/** @defgroup RecentFiles RecentFiles
 */

/** %RecentManager provides a facility for adding, removing and
 * looking up recently used files.  Each recently used file is
 * identified by its URI, and has meta-data associated to it, like
 * the names and command lines of the applications that have
 * registered it, the number of time each application has registered
 * the same file, the mime type of the file and whether the file
 * should be displayed only by the applications that have
 * registered it.
 *
 * The %RecentManager acts like a database of all the recently
 * used files.  You can create new %RecentManager objects, but
 * it is more efficient to use the default manager created by GTK+.
 *
 * @ingroup RecentFiles
 */
class GTKMM_API RecentManager : public Glib::Object
{
  _CLASS_GOBJECT(RecentManager, GtkRecentManager, GTK_RECENT_MANAGER, Glib::Object, GObject, , , GTKMM_API)

protected:
  _CTOR_DEFAULT

public:
  _WRAP_CREATE()

  _WRAP_METHOD(static Glib::RefPtr<RecentManager> get_default(), gtk_recent_manager_get_default, refreturn)

  /** Meta-data passed to add_item().  You should
   * use RecentManager::Data if you want to control the meta-data associated
   * to an entry of the recently used files list when you are adding
   * a new file to it.
   *
   * - display_name: the string to be used when displaying the file inside a RecentChooser
   * - description: a user readable description of the file
   * - mime_type: the mime type of the file
   * - app_name: the name of the application that is registering the file
   * - app_exec: the command line that should be used when launching the file
   * - groups: the list of group names to which the file belongs to
   * - is_private: whether the file should be displayed only by the applications that have registered it
  */
  class Data
  {
  public:
    Glib::ustring display_name;
    Glib::ustring description;

    Glib::ustring mime_type;

    Glib::ustring app_name;
    Glib::ustring app_exec;

    std::vector<Glib::ustring> groups;

    bool is_private;
  };

  /** Adds a new resource into the recently used resources list. This function
   * will try and guess some of the meta-data associated to a URI. If you
   * know some of meta-data about the document yourself, set the desired
   * fields of a RecentManager::Data structure and pass it to add_item().
   */
  _WRAP_METHOD(bool add_item(const Glib::ustring& uri), gtk_recent_manager_add_item, errthrow)

  /** Adds a new resource into the recently used resources list, taking
   * meta data from the given Data instead of guessing it from the URI.
   */
  bool add_item(const Glib::ustring& uri, const Data& recent_data);
  _IGNORE(gtk_recent_manager_add_full)

  _WRAP_METHOD(bool remove_item(const Glib::ustring& uri), gtk_recent_manager_remove_item, errthrow)
  _WRAP_METHOD(Glib::RefPtr<RecentInfo> lookup_item(const Glib::ustring& uri), gtk_recent_manager_lookup_item, errthrow)
  _WRAP_METHOD(Glib::RefPtr<const RecentInfo> lookup_item(const Glib::ustring& uri) const, gtk_recent_manager_lookup_item, errthrow)
  _WRAP_METHOD(bool has_item(const Glib::ustring& uri) const, gtk_recent_manager_has_item)
  _WRAP_METHOD(bool move_item(const Glib::ustring& uri, const Glib::ustring& new_uri), gtk_recent_manager_move_item, errthrow)

#m4 _CONVERSION(`GList*',`std::vector<Glib::RefPtr<RecentInfo> >',`Glib::ListHandler<Glib::RefPtr<RecentInfo>, RecentInfoTraits>::list_to_vector($3, Glib::OWNERSHIP_DEEP)')
  _WRAP_METHOD(std::vector<Glib::RefPtr<RecentInfo> > get_items() const, gtk_recent_manager_get_items)

  _WRAP_METHOD(int purge_items(), gtk_recent_manager_purge_items, errthrow)

  _WRAP_SIGNAL(void changed(), "changed")

  _WRAP_PROPERTY("filename", Glib::ustring)
  _WRAP_PROPERTY("size", int)
};

} // namespace Gtk
