Наши партнеры

Библиотека сайта rus-linux.net

Программирование с использованием gtkmm 3. Недавно использованные документы

Оригинал: Programming with gtkmm 3
Авторы: Murray Cumming, Bernhard Rieder, Jonathon Jongsma, Ole Laursen, Marko Anastasov, Daniel Elstner, Chris Vine, David King, Pedro Ferreira, Kjell Ahlstedt
Дата публикации: 15 Октября 2013 г.
Перевод: А.Панин
Дата перевода: 28 марта 2014 г.

21. Недавно использованные документы

gtkmm предоставляет простой механизм управления недавно использованными документами. Классами, связанными с реализацией данного механизма, являются: Gtk::RecentManager, Gtk::RecentChooserDialog, Gtk::RecentChooserMenu, Gtk::RecentChooserWidget, Gtk::RecentChooserAction и Gtk::RecentFilter.

Каждый элемент списка недавно использованных файлов идентифицируется с помощью строки URI и может быть ассоциирован с метаданными. Метаданные, в свою очередь, могут использоваться для указания на то, как файл должен быть показан, а также для хранения данных описания файла, его типа mime, данных о зарегистрировавшем его приложении, информации о том, используется ли он исключительно зарегистрировавшим его приложением и некоторых других данных.

21.1. Объект управления недавно использованными файлами RecentManager

Объект на основе класса Gtk::RecentManager выступает в роли базы данных недавно использованных файлов. Вы можете использовать этот объект для регистрации новых файлов, удаления файлов из списка или поиска недавно использованных файлов. При этом следует учесть, что для каждого из пользователей создается по одному списку недавно использованных файлов.

У вас есть возможность создания нового объекта на основе класса Gtk::RecentManager, но вы, скорее всего, захотите использовать стандартный объект. Ссылка на стандартный объект RecentManager может быть получена с помощью метода get_default().

Класс Gtk::RecentManager является моделью из связки модель/представление, где представлением является класс Gtk::RecentChooser, реализующий интерфейс RecentChooser.

21.1.1. Добавление элементов в список недавно использованных файлов

Для добавления нового файла в список недавно использованных документов в простейшем случае вам придется предоставить только строку URI. Например, это может быть сделано следующим образом:

Glib::RefPtr<Gtk::RecentManager> recent_manager = Gtk::RecentManager::get_default();
recent_manager->add_item(uri);

Если же вы хотите зарегистрировать файл с метаданными, вы можете передать параметр типа Gtk::RecentManager::Data методу add_item(). Определенному файлу могут быть поставлены в соответствие следующие метаданные:

app_exec: Команда оболочки, которая должна использоваться для запуска данного ресурса. Эта строка может содержать специальные символы "f" и "u", которые будут преобразовываться в путь к ресурсу и строку URI соответственно.
app_name: Имя приложения, которое зарегистрировало данный ресурс.
description: Краткое описание ресурса в формате строки, использующей кодировку UTF-8.
display_name: Видимое пользователю имя ресурса в формате строки, использующей кодировку UTF-8.
groups: Список групп, ассоциированных с данным элементом. Группы на самом деле являются произвольными строками, ассоциированными с определенным ресурсом. Они могут рассматриваться как 'категории' (такие, как "email", "graphics", и.т.д.) или тэги для данного ресурса.
is_private: Устанавливает, должен ли данный элемент списка быть виден только для зарегистрировавших его приложений или нет.
mime_type: Тип MIME данного ресурса.

В дополнение к добавлению элементов в список, вы можете искать элементы в списке, а также модифицировать или удалять их.

21.1.2. Поиск элементов в списке недавно использованных файлов

Для поиска элементов в списке недавно использованных файлов объект RecentManager предоставляет несколько функций. Для поиска определенного элемента по строке URI вы можете воспользоваться функцией lookup_item(), которая вернет экземпляр класса Gtk::RecentInfo. В том случае, если заданная строка URI не обнаруживается в списке недавно использованных файлов, функция lookup_item() сгенерирует исключение Gtk::RecentManagerError. Примером может служить следующий код:

Glib::RefPtr<Gtk::RecentInfo> info;
try
{
  info = recent_manager->lookup_item(uri);
}
catch(const Gtk::RecentManagerError& ex)
{
  std::cerr << "RecentManagerError: " << ex.what() << std::endl;
}
if (info)
{
  // элемент был найден
}

Объект на основе класса Gtk::RecentInfo на самом деле является объектом, содержащим все метаданные отдельного недавно использованного файла. Вы можете использовать этот объект для получения любых свойств файла из списка, приведенного выше.

В том случае, если вы не хотите искать элемент списка с определенной строкой URI, а вместо этого хотите получить все элементы списка недавно использованных файлов, следует обратить внимание на функцию get_items(), реализованную в рамках класса Gtk::RecentManager. Возвращаемое данной функцией значение является контейнером std::vector с объектами, соответствующими всем недавно использованным файлам. Следующий код демонстрирует способ получения списка недавно использованных файлов:

std::vector< Glib::RefPtr<Gtk::RecentInfo> > info_list = recent_manager->get_items();

Максимальный возраст элементов списка недавно использованных файлов может быть установлен с помощью метода Gtk::Settings::property_gtk_recent_files_max_age(). Стандартным значением является 30 дней.

21.1.3. Модификация списка недавно использованных файлов

Бывают моменты, когда вам может понадобиться осуществить модификацию списка недавно использованных файлов. Например, в том случае, если файл был перемещен или переименован, вы можете столкнуться с необходимостью обновления пути к файлу в списке недавно использованных файлов для того, чтобы в этом списке не было указания на уже не существующий файл. Вы можете обновить путь к элементу списка с помощью метода move_item().

В дополнение к изменению строки URI файла, вы можете удалять элементы списка либо по одному, либо все одновременно. Удаление элементов первым способом выполняется с помощью метода remove_item(), вторым - с помощью метода purge_items().

Функции move_item(), remove_item() и purge_items() не оказывают непосредственного влияния на файлы, ссылки на которые устанавливаются с помощью строк URI, а работают исключительно со списком недавно использованных файлов.

21.2. Интерфейс RecentChooser

Класс Gtk::RecentChooser является интерфейсом, который может быть реализован виджетами, выводящими список недавно использованных файлов. gtkmm предоставляет четыре встроенных реализации данного интерфейса для выбора недавно использованных файлов: Gtk::RecentChooserWidget, Gtk::RecentChooserDialog, Gtk::RecentChooserMenu и Gtk::RecentAction.

Виджет на основе класса Gtk::RecentChooserWidget является простым виджетом для показа списка недавно использованных файлов. Класс виджета Gtk::RecentChooserWidget является основным строительным блоком для класса диалога Gtk::RecentChooserDialog, но вы также можете при желании встраивать данный виджет в ваш пользовательский интерфейс.

Виджеты на основе классов Gtk::RecentChooserMenu и Gtk::RecentAction позволяют вам выводить список недавно использованных файлов в форме меню.

21.2.1. Простой пример использования диалога на основе класса Gtk::RecentChooserDialog

Ниже приведен простой пример использования классов Gtk::RecentChooserDialog и Gtk::RecentAction в программе. Этот пример программы содержит меню окна с элементом для показа диалога со списком недавно использованных файлов. В момент, когда вы выбираете этот элемент меню, происходит показ диалога со списком недавно использованных файлов.

В том случае, если вы впервые используете работающую с фреймворком недавно использованных файлов программу, в первое время список диалога не будет содержать элементов. В противном случае в списке должны находиться недавно использованные документы, зарегистрированные другими приложениями.

После выбора элемента меню с именем "Недавно использованные файлы" вы должны увидеть похожее на приведенное ниже окно.

Рисунок 21-1: Диалог со списком недавно использованных файлов

Исходный код

Файл: examplewindow.h (Для использования совместно с gtkmm 3, а не с gtkmm 2)

Файл: examplewindow.cc (Для использования совместно с gtkmm 3, а не с gtkmm 2)

#include "examplewindow.h"
#include <gtkmm/stock.h>
#include <iostream>

ExampleWindow::ExampleWindow()
: m_Box(Gtk::ORIENTATION_VERTICAL),
  m_refRecentManager(Gtk::RecentManager::get_default())
{
  set_title("Пример использования диалога со списком недавно использованных файлов");
  set_default_size(200, 200);

//Мы можем разместить меню (MenuBar) в верхней части окна, а остальные виджеты - ниже.
  add(m_Box);

//Создание действий для меню и панелей инструментов:
  m_refActionGroup = Gio::SimpleActionGroup::create();

//Меню "Файл":
  m_refActionGroup->add_action("new",
    sigc::mem_fun(*this, &ExampleWindow::on_menu_file_new));

//Элемент меню для открытия диалога со списком недавно использованных файлов:
  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();

//TODO: add_accel_group(m_refBuilder->get_accel_group());

//Строковое представление действий из меню и панели инструментов:
  const char* ui_info =
    "<interface>"
    "  <menu id='menubar'>"
    "    <submenu>"
    "      <attribute name='label' translatable='yes'>_Файл</attribute>"
    "      <item>"
    "        <attribute name='label' translatable='yes'>_Новый</attribute>"
    "        <attribute name='action'>example.new</attribute>"
    "        <attribute name='accel'>&lt;Primary&gt;n</attribute>"
    "      </item>"
    "      <item>"
    "        <attribute name='label' translatable='yes'>Недавно использованные _файлы</attribute>"
    "        <attribute name='action'>example.recent-files-dialog</attribute>"
    "        <attribute name='accel'>&lt;Primary&gt;o</attribute>"
    "      </item>"
    "      <item>"
    "        <attribute name='label' translatable='yes'>_Выход</attribute>"
    "        <attribute name='action'>example.quit</attribute>"
    "        <attribute name='accel'>&lt;Primary&gt;q</attribute>"
    "      </item>"
    "    </submenu>"
    "  </menu>";

/* TODO: 
        "  <toolbar  name='ToolBar'>"
        "    <toolitem action='FileNew'/>"
        "    <toolitem action='FileQuit'/>"
        "  </toolbar>"
        "</ui>";
*/

try
  {
    m_refBuilder->add_from_string(ui_info);
  }
  catch(const Glib::Error& ex)
  {
    std::cerr << "не удалось создать меню: " <<  ex.what();
  }

//Получение виджетов меню и панели инструментов с последующим добавлением в контейнерный виджет:
  Glib::RefPtr<Glib::Object> object =
    m_refBuilder->get_object("menubar");
  Glib::RefPtr<Gio::Menu> gmenu =
    Glib::RefPtr<Gio::Menu>::cast_dynamic(object);
  if(!gmenu)
    g_warning("Экземпляр класса Gio::Menu не найден");

//Меню:
  Gtk::MenuBar* pMenubar = new Gtk::MenuBar(gmenu);
  m_Box.pack_start(*pMenubar, Gtk::PACK_SHRINK);

/* TODO:
  Gtk::Widget* pToolbar = m_refBuilder->get_widget("/ToolBar");
  if(pToolbar)
    m_Box.pack_start(*pToolbar, Gtk::PACK_SHRINK);
*/

show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_menu_file_new()
{
  std::cout << " Новый файл" << std::endl;
}

void ExampleWindow::on_menu_file_quit()
{
  hide(); //Закрывает главное окно для выхода из функции app-<run().
}

void ExampleWindow::on_menu_file_recent_files_dialog()
{
  Gtk::RecentChooserDialog dialog(*this, "Недавно использованные файлы", m_refRecentManager);
  dialog.add_button("Выбрать файл", Gtk::RESPONSE_OK);
  dialog.add_button("_Отмена", Gtk::RESPONSE_CANCEL);

const int response = dialog.run();
  dialog.hide();
  if(response == Gtk::RESPONSE_OK)
  {
    std::cout << "Выбран файл с URI = " << dialog.get_current_uri() << std::endl;
  }
}

Файл: main.cc (Для использования совместно с gtkmm 3, а не с gtkmm 2)

Конструктор класса ExampleWindow создает меню с помощью менеджера интерфейса на основе класса Gtk::UIManager (Обратитесь к главе 12 - "Меню и панели инструментов" для получения дополнительной информации). После этого меню и панель инструментов добавляются в окно.

21.2.2. Фильтрация элементов списка недавно использованных файлов

В том случае, если вы не хотите показывать все элементы списка недавно использованных файлов, в любых классах на основе класса Gtk::RecentChooser может быть осуществлена фильтрация для вывода только тех элементов, которые вам хочется показать. Вы можете осуществить фильтрацию элементов списка с помощью экземпляра класса Gtk::RecentFilter. Этот класс позволяет вам отфильтровать недавно использованные файлы на основе их имен (add_pattern()), типов mime (add_mime_type()), приложений, которые зарегистрировали их (add_application()) или с помощью специальной функции фильтрации (add_custom()). Он также предоставляет возможность осуществления фильтрации на основе времени до последней модификации файла или его принадлежности к группам.

После того, как вы создали и настроили фильтр для извлечения только желательных элементов списка, вы можете применить фильтр к виджету выбора недавно использованных файлов с помощью функции Gtk::RecentChooser::add_filter().

Следующий раздел : 22.Коннекторы и вставки.