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

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

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

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

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

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

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

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

Примечания к функции domXml()

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

Начиная с Qt 4.4, поле виджетов Qt Designer позволяет описывать один пользовательский виджет в полном файле пользовательского интерфейса. Файл пользовательского интерфейса может быть загружен с помощью тега <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.

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

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

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

Для корректной работы плагинов на всех платформах необходимо убедиться, что они экспортируют необходимые символы для 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() плагина.

Компиляция и установка плагина

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

Пример плагина пользовательского виджета Custom Widget Plugin Example демонстрирует простой плагин 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, они не будут загружены и установлены. Для получения дополнительной информации о плагинах см. документ Плагины ПОМОЩЬ.

Также необходимо убедиться, что плагин установлен вместе с другими плагинами виджетов 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 для объединения нескольких пользовательских виджетов в одну библиотеку.