RecentChooser
| Chapter 21. Recently Used Documents |

## RecentChooser

`RecentChooser` is an interface that can be implemented by widgets displaying the list of recently used files. gtkmm provides four built-in implementations for choosing recent files: `RecentChooserWidget`, `RecentChooserDialog`, `RecentChooserMenu`, and `RecentAction`.

`RecentChooserWidget` is a simple widget for displaying a list of recently used files. `RecentChooserWidget` is the basic building block for `RecentChooserDialog`, but you can embed it into your user interface if you want to.

`RecentChooserMenu` and `RecentAction` allow you to list recently used files as a menu.

### Simple RecentChooserDialog example

Shown below is a simple example of how to use the `RecentChooserDialog` and the `RecentAction` classes in a program. This simple program has a menubar with a Recent Files Dialog menu item. When you select this menu item, a dialog pops up showing the list of recently used files.

| Note
If this is the first time you're using a program that uses the Recent Files framework, the dialog may be empty at first. Otherwise it should show the list of recently used documents registered by other applications.

After selecting the Recent Files Dialog menu item, you should see something similar to the following window.

Source Code

File: `examplewindow.h` (For use with gtkmm 3, not gtkmm 2)

    #ifndef GTKMM_EXAMPLEWINDOW_H
    #define GTKMM_EXAMPLEWINDOW_H

    #include <gtkmm.h>

    class ExampleWindow : public Gtk::Window
    {
    public:
      ExampleWindow(const Glib::RefPtr<Gtk::Application>& app);
      virtual ~ExampleWindow();

    protected:
      //Signal handlers:
      void on_menu_file_recent_files_item();
      void on_menu_file_recent_files_dialog();
      void on_menu_file_quit();
      void on_menu_file_new();

      //Child widgets:
      Gtk::Box m_Box;

      Glib::RefPtr<Gtk::Builder> m_refBuilder;
      Glib::RefPtr<Gio::SimpleActionGroup> m_refActionGroup;

      Glib::RefPtr<Gtk::RecentManager> m_refRecentManager;
    };

    #endif //GTKMM_EXAMPLEWINDOW_H

File: `examplewindow.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <iostream>

    ExampleWindow::ExampleWindow(const Glib::RefPtr<Gtk::Application>& app)
    : m_Box(Gtk::ORIENTATION_VERTICAL),
      m_refRecentManager(Gtk::RecentManager::get_default())
    {
      set_title("recent files example");
      set_default_size(200, 200);

      //We can put a MenuBar at the top of the box and other stuff below it.
      add(m_Box);

      //Create actions for menus and toolbars:
      m_refActionGroup = Gio::SimpleActionGroup::create();

      //File menu:
      m_refActionGroup->add_action("new",
        sigc::mem_fun(*this, &ExampleWindow::on_menu_file_new));

      //A menu item to open the recent-files dialog:
      m_refActionGroup->add_action("recent-files-dialog",
        sigc::mem_fun(*this, &ExampleWindow::on_menu_file_recent_files_dialog) );

      m_refActionGroup->add_action("quit",
        sigc::mem_fun(*this, &ExampleWindow::on_menu_file_quit) );

      insert_action_group("example", m_refActionGroup);

      m_refBuilder = Gtk::Builder::create();

      // When the menubar is a child of a Gtk::Window, keyboard accelerators are not
      // automatically fetched from the Gio::Menu.
      // See the examples/book/menus/main_menu example for an alternative way of
      // adding the menubar when using Gtk::ApplicationWindow.
      app->set_accel_for_action("example.new", "<Primary>n");
      app->set_accel_for_action("example.recent-files-dialog", "<Primary>o");
      app->set_accel_for_action("example.quit", "<Primary>q");

      //Layout the actions in a menubar and a toolbar:
      const char* ui_info =
        "<interface>"
        "  <menu id='menubar'>"
        "    <submenu>"
        "      <attribute name='label' translatable='yes'>_File</attribute>"
        "      <item>"
        "        <attribute name='label' translatable='yes'>_New</attribute>"
        "        <attribute name='action'>example.new</attribute>"
        "        <attribute name='accel'>&lt;Primary&gt;n</attribute>"
        "      </item>"
        "      <item>"
        "        <attribute name='label' translatable='yes'>Recent Files _Dialog</attribute>"
        "        <attribute name='action'>example.recent-files-dialog</attribute>"
        "        <attribute name='accel'>&lt;Primary&gt;o</attribute>"
        "      </item>"
        "      <item>"
        "        <attribute name='label' translatable='yes'>_Quit</attribute>"
        "        <attribute name='action'>example.quit</attribute>"
        "        <attribute name='accel'>&lt;Primary&gt;q</attribute>"
        "      </item>"
        "    </submenu>"
        "  </menu>"
        "  <object class='GtkToolbar' id='toolbar'>"
        "    <property name='visible'>True</property>"
        "    <property name='can_focus'>False</property>"
        "    <child>"
        "      <object class='GtkToolButton' id='toolbutton_new'>"
        "        <property name='visible'>True</property>"
        "        <property name='can_focus'>False</property>"
        "        <property name='tooltip_text' translatable='yes'>New</property>"
        "        <property name='action_name'>example.new</property>"
        "        <property name='icon_name'>document-new</property>"
        "      </object>"
        "      <packing>"
        "        <property name='expand'>False</property>"
        "        <property name='homogeneous'>True</property>"
        "      </packing>"
        "    </child>"
        "    <child>"
        "      <object class='GtkToolButton' id='toolbutton_quit'>"
        "        <property name='visible'>True</property>"
        "        <property name='can_focus'>False</property>"
        "        <property name='tooltip_text' translatable='yes'>Quit</property>"
        "        <property name='action_name'>example.quit</property>"
        "        <property name='icon_name'>application-exit</property>"
        "      </object>"
        "      <packing>"
        "        <property name='expand'>False</property>"
        "        <property name='homogeneous'>True</property>"
        "      </packing>"
        "    </child>"
        "  </object>"
        "</interface>";

      try
      {
        m_refBuilder->add_from_string(ui_info);
      }
      catch(const Glib::Error& ex)
      {
        std::cerr << "building menubar and toolbar failed: " <<  ex.what();
      }

      //Get the menubar and toolbar widgets, and add them to a container widget:
      auto object = m_refBuilder->get_object("menubar");
      auto gmenu = Glib::RefPtr<Gio::Menu>::cast_dynamic(object);
      if (gmenu)
      {
        //Menubar:
        auto pMenubar = Gtk::manage(new Gtk::MenuBar(gmenu));
        m_Box.pack_start(*pMenubar, Gtk::PACK_SHRINK);
      }
      else
        g_warning("GMenu not found");

      Gtk::Toolbar* pToolbar = nullptr;
      m_refBuilder->get_widget("toolbar", pToolbar);
      if (pToolbar)
        //Toolbar:
        m_Box.pack_start(*pToolbar, Gtk::PACK_SHRINK);
      else
        g_warning("GtkToolbar not found");

      show_all_children();
    }

    ExampleWindow::~ExampleWindow()
    {
    }

    void ExampleWindow::on_menu_file_new()
    {
      std::cout << " New File" << std::endl;
    }

    void ExampleWindow::on_menu_file_quit()
    {
      hide(); //Closes the main window to stop the app->run().
    }

    void ExampleWindow::on_menu_file_recent_files_dialog()
    {
      Gtk::RecentChooserDialog dialog(*this, "Recent Files", m_refRecentManager);
      dialog.add_button("Select File", Gtk::RESPONSE_OK);
      dialog.add_button("_Cancel", Gtk::RESPONSE_CANCEL);

      const int response = dialog.run();
      dialog.hide();
      if(response == Gtk::RESPONSE_OK)
      {
        std::cout << "URI selected = " << dialog.get_current_uri() << std::endl;
      }
    }

File: `main.cc` (For use with gtkmm 3, not gtkmm 2)

    #include "examplewindow.h"
    #include <gtkmm/application.h>

    int main(int argc, char *argv[])
    {
      auto app = Gtk::Application::create(argc, argv, "org.gtkmm.example");

      ExampleWindow window(app);

      //Shows the window and returns when it is closed.
      return app->run(window);
    }

The constructor for `ExampleWindow` creates the menu and the toolbar using `Builder` (see Chapter 12, Menus and Toolbars for more information). It then adds the menu and the toolbar to the window.

### Filtering Recent Files

For any of the `RecentChooser` classes, if you don't wish to display all of the items in the list of recent files, you can filter the list to show only those that you want. You can filter the list with the help of the `RecentFilter` class. This class allows you to filter recent files by their name (`add_pattern()`), their mime type (`add_mime_type()`), the application that registered them (`add_application()`), or by a custom filter function (`add_custom()`). It also provides the ability to filter based on how long ago the file was modified and which groups it belongs to.

After you've created and set up the filter to match only the items you want, you can apply a filter to a chooser widget with the `RecentChooser::add_filter()` function.

Chapter 21. Recently Used Documents |  | Chapter 22. Plugs and Sockets