Создание плагина

Создание плагина для QutIM является простым и увлекательным делом, во многом благодаря Qt.

Данная статья предполагает, что у вас есть и вы умеете пользоваться большинством из:

• git
• Qt SDK
• CMake

Перед тем как приступить к написанию плагина к QutIM, нужно раздобыть его заголовочные и библиотечные файлы. Эти файлы поставляются вместе с установщиком QutIM (речь о Windows и (?) Mac OS X), но автор статьи рекомендует всё же скачать все исходные файлы QutIM и собрать его самому, что позволит не только делать сборки для отладки, но и позволит с самого начала подготавливать исходный код плагина к публикации в репозитарии исходных кодов, а так же использовать для разработки и не поставляемый с QtSDK компилятор MSVC. Статья описывает именно такой метод.

Перво-наперво нужно склонировать репозитарий исходных кодов. Перед этим нужно, собственно, зайти (cd) в папку, в которой будет располагаться папка с исходными кодами QutIM. Всю необходимую информацию можно получить в статье Сборка QutIM из GIT. Итак, дальнейшее предусматривает, что у вас уже есть готовый, работоспособный, собранный вами лично QutIM.

Все исходники плагинов QutIM, как вы уже должны были узнать, хранятся в подпапке plugins, каждый в своей папке. Итак, создадим в этой папке папку для нашего плагина. Назовём его, для пущей убедительности, test ¹⁾. Негласные правила предлагают создать в ней подпапку src, что мы выполним.

Далее, в папке /plugins/test/ создадим файл CMakeLists.txt. Приступим к его наполнению. В общем и достаточном случае его содержимое будет такого вида:

qutim_add_plugin( <кодовое имя плагина (будет названием собранной библиотеки)>
        DISPLAY_NAME "<Человекопонятное название (отображается в списке плагинов в cmake-gui)>"
        DESCRIPTION "<Собственно описание плагина в одно-два предложения>"
	GROUP       "Plugins"
)

Таким образом CMakeLists.txt для нашего плагина test будет таким:

qutim_add_plugin( qutimtestplugin
        DISPLAY_NAME "QutIM test plugin"
        DESCRIPTION "A plugin made for test purposes only."
    	GROUP       "Plugins"
)

Имейте в виду, что этот макрос работает лишь в случае, если исходники плагина находятся рядом с CMakeLists.txt, в папке src (что у вас и должно получиться).

Создадим в папке src два файла: testplugin.h и testplugin.cpp. Понятное дело, количество исходников не ограничено, но для тестовоплагиновых целей этих файлов более чем достаточно.

В файле testplugin.h следует объявить класс плагина. Все плагины QutIM наследуют интерфейс Plugin, который располагается в файле <qutim/plugin.h> и доступен в пространстве имён qutim_sdk_0_3. Обязательным к переопределению являются методы:

• bool load() — вызывается, когда плагину требуется загрузиться и начать работать.
• bool unload() — вызывается, когда плагину следует освободить используемые им ресурсы и, собственно, выключиться. Вызывается в момент закрытия пользователем QutIM или когда пользователь выключает плагин.
• void init() — вызывается на этапе зарузки QutIM, здесь следует производить инициализацию тех вещей, которые можно инициализировать лишь один раз, а так же добавлять информацию о плагине (см. ниже).

Следуя логике замены конструктора методом load(), а деструктора — unload(), может получиться плагин, который легко включать и выключать, не перезапуская QutIM.

Для того, чтобы QutIM мог загрузить плагин, следует в определении класса плагина (в файле .cpp), но не в телах его методов, указать директиву его экспорта — QUTIM_EXPORT_PLUGIN(<имя класса). Распространённой практикой является указание диретивы последней строкой файла.

Забегая вперёд, получим немного информации.

Для метода init:

• Авторы

addAuthor(QT_TRANSLATE_NOOP("Author", "Vasya Pupkin"),
		QT_TRANSLATE_NOOP("Task", "Author"),
		QLatin1String("vapupk@example.org"));

• Собственно название плагина (будет отображаться в списке плагинов в настройках QutIM)

setInfo(QT_TRANSLATE_NOOP("Plugin", "TestPlugin"), // название
		QT_TRANSLATE_NOOP("Plugin", "A plugin made for test purposes only."), // описание
		PLUGIN_VERSION(1, 0, 0, 0), // версия
		ExtensionIcon()); // значок

При объявлении класса:

• Зависимости от сервисов

 Q_CLASSINFO("Uses", "<Название сервиса>") 

• Имя класса для отладочного вывода

 Q_CLASSINFO("DebugName", "<Название>")

При определении класса:

• Указание экспорта класса плагина

QUTIM_EXPORT_PLUGIN(<имя класса, включая пространства имён>)

#ifndef TESTPLUGIN_H
#define TESTPLUGIN_H
 
#include <qutim/plugin.h>
 
class TestPlugin : public qutim_sdk_0_3::Plugin
{
	Q_OBJECT
	Q_CLASSINFO("DebugName", "TestPlugin")
 
public:
	bool load();
	bool unload();
	void init();
};
 
#endif

void TestPlugin::init()
{
	addAuthor(QT_TRANSLATE_NOOP("Author", "Vasya Pupkin"),
			QT_TRANSLATE_NOOP("Task", "Author"),
			QLatin1String("vapupk@example.org"));
	setInfo(QT_TRANSLATE_NOOP("Plugin", "TestPlugin"), // название
			QT_TRANSLATE_NOOP("Plugin", "A plugin made for test purposes only."), // описание
			PLUGIN_VERSION(1, 0, 0, 0), // версия
			ExtensionIcon()); // значок
}

Страницы настроек в QutIM — это по сути обыкновенный QWidget, а если точнее — его наследник.

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

Все страницы настроек следует наследовать от класса qutim_sdk_0_3::SettingsWidget (заголовочный файл <qutim/settingswidget.h>). Методами, обязательными для переопределения, являются:

• void loadImpl() — здесь следует прочесть все настройки и установить контролам страницы соответствующие состояния;
• void saveImpl() — здесь следует записать настройки соответственно состояниям элеметов страницы;
• void cancelImpl() — здесь следует сбросить изменения пользователя, когда он нажал кнопку отмены.

Чтобы настройки следили за состоянием элементов управления страницы, их следует зарегистрировать для этого дела методом lookForWidgetState().

Чтобы знать, когда следует эти настройки перезагрузить, можно соединиться с сигналом объектов класса SettingsWidget saved(), испускаемым после вызова saveImpl().

Добавление страницы настроик производится методом Settings::registerItem() (файл <qutim/settingslayer.h>).

Пример:

	SettingsItem settingsItem = new GeneralSettingsItem<WSettingsWidget>(
		Settings::Plugin,	QIcon(),
		QT_TRANSLATE_NOOP("Plugin", "Test Plugin"));
	Settings::registerItem(settingsItem);

Этот класс предоставляет создателю плагина прозрачный механизм хранения настроек, работающий одинаково для любого способа их хранения.

Методы класса, обязательные к изучению:

• конструктор — инициализирует объект настроек, «настраивая» его на файл с заданным именем;
• value() — получение имеющегося значения настройки, либо её значение по-умолчанию;
• setValue() — задание и/или изменение значения настройки.

#ifndef TESTSETTINGS_H
#define TESTSETTINGS_H
#include "ui_testsettings.ui" // подключаем файл со сгенерированным классом формы из .ui-файла
 
class TestSettings : public SettingsWidget
{
	Q_OBJECT
 
public:
	TestSettings();
 
protected:
	virtual void loadImpl();
	virtual void saveImpl();
	virtual void cancelImpl();
 
private:
	Ui::TestSettingsForm *ui; // форма
 
};
#endif

#include "testsettings.h"
 
TestSettings::TestSettings()
	: ui(new Ui::TestSettingsForm)
{
	ui->setupUi(this);
	lookForWidgetState(ui->checkbox);
}
 
void TestSettings::loadImpl()
{
	Config cfg("testplugin");
	ui->checkbox->setChecked(cfg.value("showmsgbox", true));
}
 
void TestSettings::saveImpl()
{
	Config cfg("testplugin");
	cfg.setValue("showmsgbox", ui->checkbox->isChecked());
}
 
void TestSettings::cancelImpl()
{
	loadImpl();
}

В конце концов, должна получиться такая структура:

• plugins
  • testplugin
    • CmakeLists.txt
    • src
      • testplugin.h
      • testplugin.cpp
      • testsettings.h
      • testsettings.cpp
      • testsettings.ui

Исходные коды плагина можно найти тут, под именем qutimtestplugin.

Для того, чтобы ваш плагин попал в стандартный комплект, исходные коды вашего плагина должны пройти проверку разработчиками, а потом приняты в репозитарий.

Выполнение:

1. Склонируйте репозитарий плагинов на сервисе Gitorious.
2. Склонируйте клон на компьютер.
3. Оформьте исходники согласо описанным выше критериям.
4. Зафиксируйте и отправьте на сервер (commit, push).
5. Инициируйте merge request.

Ну а дальше ожидайте решения.

• Плагины
• Работа с Gitorious
• Сборка из GIT