Расширение Qt с помощью подключаемых модулей
Расширение Qt с помощью подключаемых модулей
Qt можно расширять, используя различные типы подключаемых модулей, среди которых наиболее распространенными являются драйверы баз данных, форматы изображений, стили и текстовые кодировки. Каждый тип подключаемых модулей обычно требует наличия по крайней мере двух классов: класса—оболочки, который реализует общие функции программного интерфейса подключаемых модулей, и одного или более классов—обработчиков, которые реализуют программный интерфейс для конкретного типа подключаемых модулей. Обработчики вызываются из класса—оболочки.
Ниже приведен список Qt—классов подключаемых модулей и обработчиков, исключая Qtopia Core (рис. 19.1):
• QAccessibleBridgePlugin — QAccessibleBridge,
• QAccessiblePlugin — QAccessibleIntertace,
• QIconEnginePlugin — QIconEngine,
• QImageIOPlugin — QImageIOHandler,
• QInputContextPlugin — QInputContext,
• QPictureFormatPlugin — нет обработчика,
• QSqlDriverPlugin — QSqlDriver,
• QStylePlugin — QStyle,
• QTextCodecPlugin — QTextCodec.
В демонстрационных целях мы реализуем подключаемый модуль, способный считывать в Windows монохромные файлы курсоров (файлы .cur). Эти файлы могут содержать несколько изображений разного размера для одного курсора. После построения и установки этого подключаемого модуля Qt сможет считывать файлы .cur и получать доступ к отдельным курсорам (например, с помощью классов QImage, QImageReader или QMovie); также можно будет преобразовывать эти курсоры в любой другой формат файлов изображений, воспринимаемый Qt (например, BMP, JPEG и PNG). Кроме того, подключаемый модуль может разворачиваться совместно с Qt—приложениями, поскольку они автоматически проверяют стандартные места расположения подключаемых модулей Qt и загружают все найденные модули.
Новые классы—оболочки подключаемых модулей должны быть подклассом QImageIOPlugin и должны обеспечить реализацию нескольких виртуальных функций:
01 class CursorPlugin : public QImageIOPlugin
02 {
03 public:
04 QStringList keys() const;
05 Capabilities capabilities(QIODevice *device,
06 const QByteArray &format) const;
07 QImageIOHandler *create(QIODevice *device,
08 const QByteArray &format) const;
09 };
Функция keys() возвращает список форматов изображений, которые поддерживает подключаемый модуль. Можно считать, что параметр format функций capabilities() и create() имеет значение из этого списка.
01 QStringList CursorPlugin::keys() const
02 {
03 return QStringList() << "cur";
04 }
Наш подключаемый модуль поддерживает один формат изображений, поэтому возвращается список, содержащий только одно название. В идеале это название должно совпадать с расширением файла, используемым данным форматом. Если форматы имеют несколько расширений (например, .jpg и .jpeg для JPEG), мы можем возвращать список с несколькими элементами, относящимися к одному формату, — по одному элементу на каждое расширение.
01 QImageIOPlugin::Capabilities
02 CursorPlugin::capabilities(QIODevice *device,
03 const QByteArray &format) const
04 {
05 if (format == "cur")
06 return CanRead;
07 if (format.isEmpty()) {
08 CursorHandler handler;
09 handler.setDevice(device);
10 if (handler.canRead())
11 return CanRead;
12 }
13 return 0;
14 }
Функция capabilities() возвращает объект, который показывает, что может делать с данным форматом изображений обработчик изображений. Существует три возможных действия (CanRead, CanWrite и CanReadIncremental), а возвращаемое значение объединяет допустимые варианты порязрадной логической операцией ИЛИ.
Если формат «cur», наша реализация возвращает CanRead. Если формат не задан, мы создаем обработчик курсора и проверяем его способность чтения данных с заданного устройства. Функция canRead() только просматривает данные и проверяет возможность распознавания файла, не изменяя указатель файла. Возвращение 0 означает, что данный обработчик не может ни считывать, ни записывать файл.
01 QImageIOHandler *CursorPlugin::create(QIODevice *device,
02 const QByteArray &format) const
03 {
04 CursorHandler *handler = new CursorHandler;
05 handler->setDevice(device);
06 handler->setFormat(format);
07 return handler;
08 }
Когда файл курсора открыт (например, с помощью класса QImageReader), будет вызвана функция оболочки подключаемого модуля create() с передачей указателя устройства и формата «cur». Мы создаем экземпляр CursorHandler для заданного устройства и формата. Вызывающая программа становится владельцем обработчика и удалит его, когда он не станет нужен. Если приходится считывать несколько файлов, для каждого из них создается новый обработчик.
Q_EXPORT_PLUGIN2(cursorplugin, CursorPlugin)
В конце файла .cpp мы используем макрос Q_EXPORT_PLUGIN2(), чтобы гарантировать распознавание в Qt подключаемого модуля. В первом параметре задается произвольное имя, используемое нами для подключаемого модуля. Второй параметр содержит имя класса подключаемого модуля.
Подкласс QImageIOPlugin создается достаточно просто. Реальная работа подключаемого модуля делается обработчиком. Обработчики форматов изображений должны создать подкласс QImageIOHandler и переопределить некоторые или все его открытые функции. Сначала рассмотрим заголовочный файл:
01 class CursorHandler : public QImageIOHandler
02 {
03 public:
04 CursorHandler();
05 bool canRead() const;
06 bool read(QImage *image);
07 bool jumpToNextImage();
08 int currentImageNumber() const;
09 int imageCount() const;
10 private:
11 enum State { BeforeHeader, BeforeImage, AfterLastImage, Error };
12 void readHeaderIfNecessary() const;
13 QBitArray readBitmap(int width, int height, QDataStream &in) const;
14 void enterErrorState() const;
15 mutable State state;
16 mutable int currentImageNo;
17 mutable int numImages;
18 };
Открытые функции имеют фиксированную сигнатуру. Здесь нет некоторых функций, которые не надо переопределять в обработчике, обеспечивающем только чтение, в частности отсутствует функция write(). Переменные—члены объявляются с ключевым словом mutable, потому что они изменяются внутри константных функций.
01 CursorHandler::CursorHandler()
02 {
03 state = BeforeHeader;
04 currentImageNo = 0;
05 numImages = 0;
06 }
После создания обработчика мы сначала настраиваем его параметры. Номер текущего изображения курсора устанавливается на первый курсор, но поскольку переменная количества изображений numImages принимает значение 0, ясно, что у нас пока еще нет изображений.
01 bool CursorHandler::canRead() const
02 {
03 if (state == BeforeHeader) {
04 return device()->peek(4) == QByteArray("2", 4);
05 } else {
06 return state != Error;
07 }
08 }
Функция canRead() может вызываться в любой момент для определения возможности считывания обработчиком изображений дополнительных данных с устройства. Если функция вызывается до чтения данных в состоянии BeforeHeader, выполняется проверка конкретной метки, по которой опознаются файлы курсоров в Windows. Вызов QIODevice::peek() считывает первые четыре байта без изменения указателя файла на данном устройстве. Если функция canRead() вызывается позже, мы возвращаем true при отсутствии ошибки.
01 int CursorHandler::currentImageNumber() const
02 {
03 return currentImageNo;
04 }
Эта простая функция возвращает номер курсора, на который позиционирован указатель файла устройства.
После создания обработчика пользователь может вызвать любую его открытую функцию, причем последовательность вызовов функций может быть произвольной. В этом кроется потенциальная проблема, поскольку необходимо исходить из того, что файл можно читать только последовательно, поэтому сначала надо один раз считать заголовок файла и затем выполнять какие-то другие действия. Эту проблему решаем путем вызова readHeaderIfNecessary() в тех функциях, для которых требуется предварительное считывание заголовка файла.
01 int CursorHandler::imageCount() const
02 {
03 readHeaderIfNecessary();
04 return numImages;
05 }
Эта функция возвращает количество изображений, содержащихся в файле. Для правильного файла, при чтении которого не возникает ошибок, она возвращает по крайней мере 1.
Рис. 19.2. Формат файла .cur.
Следующая функция довольно сложная, поэтому мы рассмотрим ее по частям:
01 bool CursorHandler::read(QImage *image)
02 {
03 readHeaderIfNecessary();
04 if (state != BeforeImage)
05 return false;
Функция read() считывает данные изображения, начинающегося в текущей позиции указателя устройства. Если успешно считан заголовок файла или указатель устройства после чтения изображения находится в начале другого изображения, можно считывать следующее изображение.
06 quint32 size;
07 quint32 width;
08 quint32 height;
09 quint16 numPlanes;
10 quint16 bitsPerPixel;
11 quint32 compression;
12 QDataStream in(device());
13 in.setByteOrder(QDataStream::LittleEndian);
14 in >> size;
15 if (size != 40) {
16 enterErrorState();
17 return false;
18 }
19 in >> width >> height >> numPlanes >> bitsPerPixel >> compression;
20 height /= 2;
21 if (numPlanes != 1 || bitsPerPixel != 1 || compression != 0) {
22 enterErrorState();
23 return false;
24 }
25 in.skipRawData((size - 20) + 8);
Мы создаем объект QDataStream для чтения устройства. Необходимо установить порядок байтов в соответствии с тем, который определен спецификацией формата файла .cur. Задавать версию потока QDataStream нет необходимости, поскольку форматы целых чисел и чисел с плавающей запятой не зависят от версии потока данных. Затем считываем элементы заголовка курсора и пропускаем неиспользуемые части заголовка и 8-байтовую таблицу цветов с помощью функции QDataStream::skipRawData().
Необходимо учитывать все характерные особенности формата, например, уменьшая вдвое высоту изображения, потому что она в формате .cur в два раза превышает высоту реального изображения. Переменные bitsPerPixel и compression всегда имеют значения 1 и 0 в монохромных файлах .cur. При возникновении каких-либо проблем вызываем функцию enterErrorState() и возвращаем false.
26 QBitArray xorBitmap = readBitmap(width, height, in);
27 QBitArray andBitmap = readBitmap(width, height, in);
28 if (in.status() != QDataStream::Ok) {
29 enterErrorState();
30 return false;
31 }
Следующими элементами файла являются две битовые маски: одна XOR—маска, а другая AND—маска. Мы их считываем в массивы QBitArray, а не в QBitmap. Класс QBitmap предназначен для выполнения с ним операций рисования и вывода рисунка на экран, а нам нужен простой массив битов.
Завершив чтение файла, проверяем состояние потока QDataStream. Так можно поступать, потому что, если QDataStream переходит в состояние ошибки, это состояние сохраняется в дальнейшем и последующие операции чтения могут выдать только нули. Например, если чтение первого массива бит завершается неудачей, попытка чтения второго массива в результате даст пустой массив QBitArray.
32 *image = QImage(width, height, QImage::Format_ARGB32);
33 for (int i = 0; i < int(height); ++i) {
34 for (int j = 0; j < int(width); ++j) {
35 QRgb color;
36 int bit = (i * width) + j;
37 if (andBitmap.testBit(bit)) {
38 if (xorBitmap.testBit(bit)) {
39 color = 0x7F7F7F7F;
40 } else {
41 color = 0x00FFFFFF;
42 }
43 } else {
44 if (xorBitmap.testBit(bit)) {
45 color = 0xFFFFFFFF;
46 } else {
47 color = 0xFF000000;
48 }
50 }
51 image->setPixel(j, i, color);
52 }
53 }
Мы конструируем новый объект QImage с правильными размерами и устанавливаем на него указатель изображения. Затем проходим по каждому пикселю битовых массивов XOR и AND и преобразуем их в 32-битовый цветовой формат ARGB. С помощью массивов битов AND и XOR цвет каждого пикселя курсора всегда получается в соответствии со следующей таблицей:
С получением черного, белого и прозрачного пикселей нет проблем, однако нельзя получить инвертированный пиксель фона, используя цветовой формат ARGB, если не знаешь цвет исходного пикселя фона. В качестве замены используем полупрозрачный серый цвет (0x7F7F7F7F).
54 ++currentImageNo;
55 if (currentImageNo == numImages)
56 state = AfterLastImage;
57 return true;
58 }
Завершив чтение изображения, мы обновляем текущий номер изображения и обновляем состояние, если прочитано последнее изображение. В конце функции устройство будет указывать на начало следующего изображения или на конец файла.
01 bool CursorHandler::jumpToNextImage()
02 {
03 QImage image;
04 return read(&image);
05 }
Функция jumpToNextImage() используется для пропуска изображения. Для простоты мы всего лишь вызываем read() и игнорируем полученный QImage. В более эффективной реализации использовалась бы информация, содержащаяся в заголовке файла .cur, для непосредственного смещения по файлу на соответствующее значение.
01 void CursorHandler::readHeaderIfNecessary() const
02 {
03 if (state != BeforeHeader)
04 return;
05 quint16 reserved;
06 quint16 type;
07 quint16 count;
08 QDataStream in(device());
09 in.setByteOrder(QDataStream::LittleEndian);
10 in >> reserved >> type >> count;
11 in.skipRawData(16 * count);
12 if (in.status() != QDataStream::Ok || reserved != 0
13 || type != 2 || count == 0) {
14 enterErrorState();
15 return;
16 }
17 state = BeforeImage;
18 currentImageNo = 0;
19 numImages = int(count);
20 }
Закрытая функция readHeaderIfNecessary() вызывается из imageCount() и read(). Если заголовок файла уже был прочитан, состояние не будет иметь значение BeforeHeader (перед заголовком) и сразу же делается возврат управления. В противном случае открываем на устройстве поток данных, считываем некоторые общие данные (в частности, количество курсоров, содержащихся в файле) и устанавливаем состояние в значение BeforeImage (перед изображением). В конце указатель файла данного устройства устанавливается перед первым изображением.
01 void CursorHandler::enterErrorState() const
02 {
03 currentImageNo = 0;
04 numImages = 0;
05 state = Error;
06 }
При возникновении ошибки считаем, что файл не содержит изображений требуемого формата, и устанавливаем состояние в значение Error. В дальнейшем такое состояние обработчика не может быть изменено.
01 QBitArray CursorHandler::readBitmap(int width, int height,
02 QDataStream &in) const
03 {
04 QBitArray bitmap(width * height);
05 quint8 byte;
06 quint32 word;
07 for (int i = 0; i < height; ++i) {
08 for (int j = 0; j < width; ++j) {
09 if ((j % 32) == 0) {
10 word = 0;
11 for (int k = 0; k < 4; ++k) {
12 in >> byte;
13 word = (word << 8) | byte;
14 }
15 }
16 bitmap.setBit(((height - i - 1) * width) + j,
17 word & 0x80000000);
18 word <<= 1;
19 }
20 }
21 return bitmap;
22 }
Функция readBitmap() используется для чтения масок курсора AND и XOR. Эти маски обладают двумя необычными свойствами. Во-первых, строки в них располагаются, начиная с нижних, вместо обычного расположения строк сверху вниз. Во-вторых, оказывается, что используемый здесь порядок байтов отличается от порядка байтов любых других данных в файлах .cur. В связи с этим нам приходится инвертировать координату у в вызове setBit() и считывать маски побайтно, сдвигая биты и используя маску для получения правильных значений.
Этим завершается реализация класса CursorHandler — подключаемого модуля, предназначенного для работы с изображениями курсоров. Подключаемые модули для изображений других форматов могли бы создаваться аналогично, хотя в некоторых случаях может потребоваться реализация дополнительных функций программного интерфейса QImageIOHandler, в частности функций, используемых для записи изображений. Подключаемые модули другого вида, например кодировки текста или драйверы баз данных, создаются по тому же самому образцу: реализуются класс—оболочка, обеспечивающий общий программный интерфейс подключаемых модулей, который может использоваться приложением, и обработчик, обеспечивающий базовую функциональность.
Файл .pro для подключаемых модулей отличается от файлов .pro, используемых для приложений, поэтому мы покажем его состав:
TEMPLATE = lib
CONFIG += plugin
HEADERS = cursorhandler.h
cursorplugin.h
SOURCES = cursorhandler.cpp
cursorplugin.cpp
DESTDIR = $(QTDIR)/plugins/imageformats
По умолчанию файлы .pro используют шаблон app, но здесь мы должны указать шаблон lib, потому что подключаемый модуль является библиотекой, а не автономным приложением. Строка с элементом CONFIG указывает Qt на то, что у нас не простая библиотека, а библиотека подключаемого модуля. Элемент DESTDIR определяет каталог размещения подключаемого модуля. Каждый подключаемый модуль Qt должен находиться в соответствующем подкаталоге каталога plugins, и поскольку наш подключаемый модуль обеспечивает новый формат изображений, помещаем его в plugins/imageformats. Список имен каталогов и типов подключаемых модулей приводится на веб-странице http://doc.trolltech.com/4.1/plugins-howto.html. В данном случае мы предполагаем, что переменная среды QTDIR определяет каталог, в котором находится Qt.
Для Qt в рабочем (release) и отладочном (debug) режимах создаются различные подключаемые модули, поэтому, если установлены обе версии Qt, имеет смысл указать в файле .pro ту из них, которая будет использоваться, добавляя строку
CONFIG += release
Приложения, использующие подключаемые модули Qt, должны разворачиваться совместно со своими подключаемыми модулями. Подключаемые модули Qt должны располагаться в конкретных подкаталогах (например, в imageformats для форматов изображений). Приложения Qt ищут подключаемые модули в каталоге plugins, который располагается в каталоге размещения исполняемого модуля приложения, поэтому поиск подключаемых модулей изображений будет выполняться в application_dir/plugins/imageformats. Если требуется развернуть подключаемые модули Qt в другом каталоге, можно установить дополнительный путь поиска, используя функцию QCoreApplication::addLibraryPath().