Создание пользовательских виджетов для Qt Designer

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

Модуль QtDesigner предоставляет возможность создавать пользовательские виджеты в Qt Designer.

Начало работы

Для интеграции пользовательского виджета с Qt Designer, требуется подходящее описание виджета и соответствующий .pro файл.

Предоставление описания интерфейса

Чтобы проинформировать Qt Designer о типе виджета, создайте подкласс QDesignerCustomWidgetInterface, который описывает различные свойства вашего виджета. Большинство из них предоставляются функциями, которые являются чисто виртуальными в базовом классе, потому что только автор плагина может предоставить эту информацию.

Также можно переопределить две другие виртуальные функции:

Замечания по функции domXml()

Функция domXml() возвращает фрагмент файла UI, который используется фабрикой виджетов Qt Designer для создания пользовательского виджета и его соответствующих свойств.

Начиная с Qt 4.4, поле виджетов Qt Designer позволяет использовать весь файл UI для описания одного пользовательского виджета. Файл UI можно загрузить с помощью тега <ui>. Указание тега <ui> позволяет добавить элемент <customwidget>, который содержит дополнительную информацию для пользовательских виджетов. Тег <widget> достаточен, если дополнительная информация не требуется.

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

    ...
           "  <property name=\"geometry\">\n"
           "   <rect>\n"
           "    <x>0</x>\n"
           "    <y>0</y>\n"
           "    <width>100</width>\n"
           "    <height>100</height>\n"
           "   </rect>\n"
           "  </property>\n"
    ...

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

Полное описание пользовательского виджета выглядит следующим образом:

<ui language="c++"> displayname="MyWidget">
    <widget class="widgets::MyWidget" name="mywidget"/>
    <customwidgets>
        <customwidget>
            <class>widgets::MyWidget</class>
            <addpagemethod>addPage</addpagemethod>
            <propertyspecifications>
                <stringpropertyspecification name="fileName" notr="true" type="singleline"/>
                <stringpropertyspecification name="text" type="richtext"/>
                <tooltip name="text">Explanatory text to be shown in Property Editor</tooltip>
            </propertyspecifications>
        </customwidget>
    </customwidgets>
</ui>

Атрибуты тега <ui>:

Тег <addpagemethod> сообщает Qt Designer и uic, какой метод следует использовать для добавления страниц в контейнерный виджет. Это относится к контейнерным виджетам, для которых требуется вызов определенного метода для добавления дочернего элемента, а не добавление дочернего элемента путем передачи родителя. В частности, это актуально для контейнеров, которые не являются подклассами контейнеров, предоставляемых в Qt Designer, но основаны на понятии Текущей страницы. Кроме того, для них необходимо предоставить расширение контейнера.

Элемент <propertyspecifications> может содержать список метаинформации о свойствах.

Тег <tooltip> может использоваться для указания подсказки инструмента, которая отображается в редакторе свойств при наведении курсора на свойство. Имя свойства указано в атрибуте name, а текст элемента — это подсказка инструмента. Эта функциональность была добавлена в Qt 5.6.

Для свойств типа строка можно использовать тег <stringpropertyspecification>. У этого тега есть следующие атрибуты:

Значения атрибута type свойства типа строка:

Требования к плагину

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

Прежде всего, класс плагина должен быть экспортирован, чтобы плагин мог быть загружен Qt Designer. Используйте макрос Q_PLUGIN_METADATA() для этого. Также макрос QDESIGNER_WIDGET_EXPORT должен быть использован для определения каждого класса пользовательского виджета внутри плагина, который Qt Designer будет инициализировать.

Создание корректных виджетов

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

Для придания пользовательским виджетам специального поведения в Qt Designer, предоставьте реализацию функции initialize() для настройки процесса создания виджета для поведения, специфичного для Qt Designer. Эта функция будет вызвана в первый раз до любых вызовов createWidget() и, возможно, установит внутренний флаг, который можно будет проверить позже, когда Qt Designer вызовет функцию createWidget() плагина.

Сборка и установка плагина

Простой плагин

Пример Плагина пользовательского виджета демонстрирует простой плагин Qt Designer.

Файл .pro для плагина должен указывать заголовки и исходные файлы как для пользовательского виджета, так и для интерфейса плагина. Как правило, этот файл должен только указать, что проект плагина должен быть скомпилирован как библиотека, но с поддержкой плагина для Qt Designer. Это делается с помощью следующих объявлений:

QT          += widgets uiplugin
CONFIG      += plugin
TEMPLATE    = lib

Переменная QT содержит ключевое слово uiplugin. Это указывает, что плагин использует только абстрактные интерфейсы QDesignerCustomWidgetInterface и QDesignerCustomWidgetCollectionInterface и не связан с библиотеками Qt Designer. При обращении к другим интерфейсам Qt Designer, имеющим связь, следует использовать designer; это гарантирует, что плагин динамически подключается к библиотекам Qt Designer и имеет от него зависимость во время выполнения.

Если плагины построены в режиме, несовместимом с Qt Designer, они не будут загружены и установлены. Для получения дополнительной информации о плагинах см. документ Плагины HOWTO.

Также необходимо убедиться, что плагин установлен вместе с другими плагинами виджетов Qt Designer:

target.path = $$[QT_INSTALL_PLUGINS]/designer
INSTALLS += target

Переменная $[QT_INSTALL_PLUGINS] является заглушкой для расположения установленных плагинов Qt. Вы можете настроить Qt Designer на поиск плагинов в других расположениях, задав переменную среды QT_PLUGIN_PATH перед запуском приложения.

Примечание: Qt Designer будет искать подкаталог designer в каждом предоставленном пути.

См. QCoreApplication::libraryPaths() для получения дополнительной информации о настройке путей для библиотек и плагинов в приложениях Qt.

Разделение плагина

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

Следующие разделы описывают, как это исправить.

Связывание виджета с приложением

Исходный и заголовочный файлы пользовательского виджета можно совместно использовать между приложением и Qt Designer, создав файл .pri для включения:

INCLUDEPATH += $$PWD
HEADERS += $$PWD/analogclock.h
SOURCES += $$PWD/analogclock.cpp

Затем этот файл будет включён в файл .pro плагина и приложения:

include(customwidget.pri)

Обмен виджетом с помощью библиотеки

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

Для общих библиотек см. Создание общих библиотек.

Использование плагина с QUiLoader

Предпочтительный способ добавления пользовательских виджетов в QUiLoader — это наследование от него с переопределением QUiLoader::createWidget().

Однако также можно использовать пользовательские плагины виджетов Qt Designer (см. QUiLoader::pluginPaths() и связанные функции). Чтобы избежать необходимости развертывания библиотек Qt Designer на целевом устройстве, эти плагины не должны иметь связи с библиотеками Qt Designer (QT = uiplugin, см. Создание пользовательских виджетов для Qt Designer#BuildingandInstallingthePlugin).

Связанные примеры

Для получения дополнительной информации об использовании пользовательских виджетов в Qt Designer, обратитесь к примерам Плагин пользовательского виджета и Плагин мирового времени для получения дополнительной информации об использовании пользовательских виджетов в Qt Designer. Также вы можете использовать класс QDesignerCustomWidgetCollectionInterface для объединения нескольких пользовательских виджетов в одну библиотеку.