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

Библиотека сайта 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 г.

19. Буфер обмена

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

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

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

Справочная информация

19.1. Цели

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

Например, приложение gedit может предоставлять и принимать цель "UTF8_STRING", поэтому вы можете вставить данные, переданные любым предоставляющим эту цель приложением, в поле редактирования текста приложения gedit. Также два приложения для редактирования изображений могут предоставлять и принимать изображения во множестве форматов, рассматривая эти форматы в качестве целей. Если одно приложение может принимать одну из целей, которую также предоставляет другое приложение, у вас будет возможность копировать данные из одного приложения в другое.

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

API захвата и перемещения данных (Drag and Drop) использует аналогичный механизм. Вам, скорее всего, придется использовать одни и те же цели и форматы данных как для операций с буфером обмена, так и операций захвата и перемещения данных.

19.2. Копирование

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

Примером может служить следующий код:

Glib::RefPtr<Gtk::Clipboard> refClipboard = Gtk::Clipboard::get();

//Цели:
std::vector<Gtk::TargetEntry> targets;
targets.push_back( Gtk::TargetEntry("example_custom_target") );
targets.push_back( Gtk::TargetEntry("UTF8_STRING") );

refClipboard->set( targets,
    sigc::mem_fun(*this, &ExampleWindow::on_clipboard_get),
    sigc::mem_fun(*this, &ExampleWindow::on_clipboard_clear) );

После этого ваш метод обратного вызова передаст сохраненные данные в момент, когда пользователь осуществит вставку данных. Этот метод может быть реализован следующим образом:

void ExampleWindow::on_clipboard_get(
    Gtk::SelectionData& selection_data, guint /* info */)
{
  const std::string target = selection_data.get_target();

  if(target == "example_custom_target")
    selection_data.set("example_custom_target", m_ClipboardStore);
}

В идеальном примере ниже может передаваться более чем одна цель буфера обмена.

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

19.3. Вставка

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

refClipboard->request_contents("example_custom_target",
    sigc::mem_fun(*this, &ExampleWindow::on_clipboard_received) );

А ниже приведен пример метода обратного вызова:

void ExampleWindow::on_clipboard_received(
    const Gtk::SelectionData& selection_data)
{
  Glib::ustring clipboard_data = selection_data.get_data_as_string();
  //Выполнение каких-либо операций с вставленными данными.
}

19.3.1. Установление доступных целей

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

refClipboard->request_targets( sigc::mem_fun(*this,
    &ExampleWindow::on_clipboard_received_targets) );

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

void ExampleWindow::on_clipboard_received_targets(
  const std::vector<Glib::ustring>& targets)
{
  const bool bPasteIsPossible =
    std::find(targets.begin(), targets.end(),
      example_target_custom) != targets.end();

  // Активация/дективация элемента "Вставить" в соответствии с наличием возможности вставки данных:
  m_Button_Paste.set_sensitive(bPasteIsPossible);
}

19.4. Примеры

19.4.1. Простой пример

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

Рисунок 19-1: Буфер обмена - Простой пример

Исходный код

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

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

#include "examplewindow.h"

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::ORIENTATION_VERTICAL),
  m_Label("Выберите ячейки сетки, нажмите \"Копировать\", после чего откройте второй\n"
        "экземпляр этого примера и попытайтесь вставить скопированные данные."),
  m_ButtonA1("A1"), m_ButtonA2("A2"), m_ButtonB1("B1"), m_ButtonB2("B2"),
  m_Button_Copy("_Копировать", /* mnemonic= */ true), m_Button_Paste("_Вставить", true)
{
  set_title("Пример использования класса Gtk::Clipboard");
  set_border_width(12);

add(m_VBox);

m_VBox.pack_start(m_Label, Gtk::PACK_SHRINK);

//Заполнение сетки:
  m_VBox.pack_start(m_Grid);
  m_Grid.set_row_homogeneous(true);
  m_Grid.set_column_homogeneous(true);
  m_Grid.attach(m_ButtonA1, 0, 0, 1, 1);
  m_Grid.attach(m_ButtonA2, 1, 0, 1, 1);
  m_Grid.attach(m_ButtonB1, 0, 1, 1, 1);
  m_Grid.attach(m_ButtonB2, 1, 1, 1, 1);

//Добавление контейнера для кнопок снизу:
  m_VBox.pack_start(m_ButtonBox, Gtk::PACK_SHRINK);
  m_VBox.set_spacing(6);

//Заполнение контейнера для кнопок:
  m_ButtonBox.set_layout(Gtk::BUTTONBOX_END);
  m_ButtonBox.pack_start(m_Button_Copy, Gtk::PACK_SHRINK);
  m_Button_Copy.signal_clicked().connect(sigc::mem_fun(*this,
              &ExampleWindow::on_button_copy) );
  m_ButtonBox.pack_start(m_Button_Paste, Gtk::PACK_SHRINK);
  m_Button_Paste.signal_clicked().connect(sigc::mem_fun(*this,
              &ExampleWindow::on_button_paste) );

show_all_children();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_copy()
{
  //Создание строкового представления скопированных данных:
  //В идеале вы должны использовать здесь язык разметки XML вместе с системой разбора документов XML:
  Glib::ustring strData;
  strData += m_ButtonA1.get_active() ? "1" : "0";
  strData += m_ButtonA2.get_active() ? "1" : "0";
  strData += m_ButtonB1.get_active() ? "1" : "0";
  strData += m_ButtonB2.get_active() ? "1" : "0";

Glib::RefPtr<Gtk::Clipboard> refClipboard = Gtk::Clipboard::get();
  refClipboard->set_text(strData);
}

void ExampleWindow::on_button_paste()
{
  //Сообщение объекту буфера обмена о том, что он должен вызвать метод обратного вызова в момент готовности:
  Glib::RefPtr<Gtk::Clipboard> refClipboard = Gtk::Clipboard::get();
  refClipboard->request_text(sigc::mem_fun(*this,
              &ExampleWindow::on_clipboard_text_received) );
}

void ExampleWindow::on_clipboard_text_received(const Glib::ustring& text)
{
  //Обратите внимание на комментарий в методе on_button_copy() относительно этого странного формата данных для буфера обмена.
  if(text.size() >= 4)
  {
    m_ButtonA1.set_active( text[0] == '1' );
    m_ButtonA2.set_active( text[1] == '1' );
    m_ButtonB1.set_active( text[2] == '1' );
    m_ButtonB2.set_active( text[3] == '1' );
  }
}

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

19.4.2. Идеальный пример

Этот пример похож на простой пример, но он

Устанавливает специальную цель для буфера обмена, хотя форматом этой цели все равно является текст.
Поддерживает вставку с использованием 2 целей - как с помощью специальной цели, так и с помощью текстовой цели, которая создает произвольное текстовое представление специфических данных.
Использует метод request_targets() и сигнал "owner_change" и деактивирует кнопку "Вставить" в том случае, если данные из буфера не могут быть использованы.

Рисунок 19-2: Буфер обмена - Идеальный пример

Исходный код

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

#ifndef GTKMM_EXAMPLEWINDOW_H
#define GTKMM_EXAMPLEWINDOW_H

#include <gtkmm.h>

class ExampleWindow : public Gtk::Window
{
public:
  ExampleWindow();
  virtual ~ExampleWindow();

protected:
  //Обработчики сигналов:
  void on_button_copy();
  void on_button_paste();

void on_clipboard_owner_change(GdkEventOwnerChange* event);
  void on_clipboard_get(Gtk::SelectionData& selection_data, guint info);
  void on_clipboard_clear();

void on_clipboard_received(const Gtk::SelectionData& selection_data);
  void on_clipboard_received_targets(const std::vector<Glib::ustring>& targets);
   
  virtual void update_paste_status(); //Деактивация кнопки "Вставить" в том случае, если пригодных для вставки данных нет.

//Дочерние виджеты:
  Gtk::Box m_VBox;

Gtk::Label m_Label;
  
  Gtk::Grid m_Grid;
  Gtk::ToggleButton m_ButtonA1, m_ButtonA2, m_ButtonB1, m_ButtonB2;

Gtk::ButtonBox m_ButtonBox;
  Gtk::Button m_Button_Copy, m_Button_Paste;

Glib::ustring m_ClipboardStore; //Переменная для сохранения скопированных данных до момента их вставки. Эта переменная может представлять большую и сложную структуру данных.
};

#endif //GTKMM_EXAMPLEWINDOW_H

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

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

namespace
{

//Обычно это должны быть типы MIME.
const char example_target_custom[] = "gtkmmclipboardexample";
const char example_target_text[]   = "UTF8_STRING";

} // анонимное пространство имен

ExampleWindow::ExampleWindow()
: m_VBox(Gtk::ORIENTATION_VERTICAL),
  m_Label("Выберите ячейки сетки, нажмите \"Копировать\", после чего откройте второй экземпляр\n"
          "этого примера и попытайтесь вставить скопированные данные.\n"
          "Или попытайтесь вставить текстовое представление скопированных данных в gedit."),
  m_ButtonA1("A1"), m_ButtonA2("A2"), m_ButtonB1("B1"), m_ButtonB2("B2"),
  m_Button_Copy("_Копировать", /* mnemonic= */ true), m_Button_Paste("_Вставить", true)
{
  set_title("Пример использования класса Gtk::Clipboard");
  set_border_width(12);

add(m_VBox);

m_VBox.pack_start(m_Label, Gtk::PACK_SHRINK);

//Добавление контейнера для кнопок снизу:
  m_VBox.pack_start(m_ButtonBox, Gtk::PACK_SHRINK);
  m_VBox.set_spacing(6);

//Установка обработчика сигнала, который будет вызван тогда, когда содержимое
  //буфера обмена изменится.
  Gtk::Clipboard::get()->signal_owner_change().connect(sigc::mem_fun(*this,
              &ExampleWindow::on_clipboard_owner_change) );

show_all_children();

update_paste_status();
}

ExampleWindow::~ExampleWindow()
{
}

void ExampleWindow::on_button_copy()
{
  //Формирование строкового представления копируемых данных:
  //В идеальном случае вы должны использовать здесь формат разметки XML вместе с системой разбора документов XML:
  Glib::ustring strData;
  strData += m_ButtonA1.get_active() ? "1" : "0";
  strData += m_ButtonA2.get_active() ? "1" : "0";
  strData += m_ButtonB1.get_active() ? "1" : "0";
  strData += m_ButtonB2.get_active() ? "1" : "0";

Glib::RefPtr<Gtk::Clipboard> refClipboard = Gtk::Clipboard::get();

//Цели:
  std::vector<Gtk::TargetEntry> targets;

targets.push_back( Gtk::TargetEntry(example_target_custom) );
  targets.push_back( Gtk::TargetEntry(example_target_text) );

refClipboard->set(targets,
    sigc::mem_fun(*this, &ExampleWindow::on_clipboard_get),
    sigc::mem_fun(*this, &ExampleWindow::on_clipboard_clear) );

//Сохранение скопированных данных до момента их вставки:
  //(Должно быть выполнено перед вызовом refClipboard->set(), так как этот вызов
  //может привести к вызову обработчика on_clipboard_clear.)
  m_ClipboardStore = strData;

update_paste_status();
}

void ExampleWindow::on_button_paste()
{
  //Сообщение объекту буфера обмена о том, что наш метод должен быть вызван при готовности данных:
  Glib::RefPtr<Gtk::Clipboard> refClipboard = Gtk::Clipboard::get();

refClipboard->request_contents(example_target_custom, 
    sigc::mem_fun(*this, &ExampleWindow::on_clipboard_received) );

update_paste_status();
}

void ExampleWindow::on_clipboard_owner_change(GdkEventOwnerChange*)
{
  update_paste_status();
}

void ExampleWindow::on_clipboard_get(Gtk::SelectionData& selection_data,
  guint /* info */)
{
  // Параметр info соответствует необязательному параметру info конструктора класса
  // Gtk::TargetEntry. Мы используем не его, а строковое описание цели target полученное из объекта selection_data вместо него.

const std::string target = selection_data.get_target();

if(target == example_target_custom)
  {
    // Данный перекрытый метод set() использует 8-ми битный текстовый формат для данных.
    selection_data.set(example_target_custom, m_ClipboardStore);
  }
  else if(target == example_target_text)
  {
    //Создание произвольного текстового представления данных
    //для того, чтобы люди увидели что-либо при вставке скопированных данных в текстовый редактор:
    Glib::ustring text_representation;

text_representation += m_ButtonA1.get_active() ? "A1, " : "";
    text_representation += m_ButtonA2.get_active() ? "A2, " : "";
    text_representation += m_ButtonB1.get_active() ? "B1, " : "";
    text_representation += m_ButtonB2.get_active() ? "B2, " : "";

selection_data.set_text(text_representation);
  }
  else
  {
    g_warning("ExampleWindow::on_clipboard_get(): "
            "Неизвестный формат цели данных текстового буфера.");
  }
}

void ExampleWindow::on_clipboard_clear()
{
  //На самом деле этот вызов не является необходимым. Но я думаю, что он поможет сохранить память.
  m_ClipboardStore.clear();
}

void ExampleWindow::on_clipboard_received(
        const Gtk::SelectionData& selection_data)
{
  const std::string target = selection_data.get_target();

//Данный код всегда должен присутствовать, так как мы запрашивали эти данные при
  //вызове метода request_contents().
  if(target == example_target_custom)
  {
    Glib::ustring clipboard_data = selection_data.get_data_as_string();

//Обратите внимание на комментарий в методе on_button_copy() относительно данного странного формата данных буфера обмена.
    if(clipboard_data.size() >= 4)
    {
      m_ButtonA1.set_active( clipboard_data[0] == '1' );
      m_ButtonA2.set_active( clipboard_data[1] == '1' );
      m_ButtonB1.set_active( clipboard_data[2] == '1' );
      m_ButtonB2.set_active( clipboard_data[3] == '1' );
    }
  }
}

void ExampleWindow::update_paste_status()
{
  //Деактивация кнопки "Вставить" в том случае, если нет пригодных для вставки данных.

Glib::RefPtr<Gtk::Clipboard> refClipboard = Gtk::Clipboard::get();

//Исследование доступных целей:
  refClipboard->request_targets(sigc::mem_fun(*this,
              &ExampleWindow::on_clipboard_received_targets) );
}

void ExampleWindow::on_clipboard_received_targets(
  const std::vector<Glib::ustring>& targets)
{
  const bool bPasteIsPossible =
    std::find(targets.begin(), targets.end(),
      example_target_custom) != targets.end();

// Активация/деактивация кнопки "Вставить" в зависимости от полученных данных:
  m_Button_Paste.set_sensitive(bPasteIsPossible);
}

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

Следующий раздел : 20.Печать.