Класс QQuickWidget

Класс QQuickWidget предоставляет виджет для отображения пользовательского интерфейса Qt Quick. Подробнее...

• Список всех членов, включая унаследованные

Типы

Свойства

• resizeMode : ResizeMode
• source : QUrl
• status : const Status

Открытые функции

Открытые слоты

Сигналы

Переопределенные защищенные функции

Подробное описание

Это удобная обертка для QQuickWindow, которая автоматически загрузит и отобразит сцену QML, когда ей будет предоставлен URL-адрес основного исходного файла. В качестве альтернативы вы можете создать собственные объекты с помощью QQmlComponent и разместить их в вручную настроенном QQuickWidget.

Типичное использование:

QQuickWidget *view = new QQuickWidget;
view->setSource(QUrl::fromLocalFile("myqmlfile.qml"));
view->show();

Чтобы получать ошибки, связанные с загрузкой и выполнением QML с QQuickWidget, вы можете подключиться к сигналу statusChanged() и отслеживать QQuickWidget::Error. Ошибки доступны через QQuickWidget::errors().

QQuickWidget также управляет размером представления и корневого объекта. По умолчанию resizeMode равен SizeViewToRootObject, который загрузит компонент и изменит его размер в соответствии с размером представления. В качестве альтернативы, resizeMode может быть установлен в SizeRootObjectToView, который изменит размер представления в соответствии с размером корневого объекта.

Примечание: QQuickWidget — это альтернатива использованию QQuickView и QWidget::createWindowContainer(). Ограничения по порядку стека не применяются, что делает QQuickWidget более гибкой альтернативой, ведя себя как обычный виджет. Это происходит за счет производительности. В отличие от QQuickWindow и QQuickView, QQuickWidget включает отрисовку в буферы OpenGL framebuffer. Это естественно, несет за собой незначительные потери производительности.

Примечание: Использование QQuickWidget отключает потоковый цикл отрисовки на всех платформах. Это означает, что некоторые преимущества потоковой отрисовки, например, классы Animator и анимированные процессы, управляемые vsync, будут недоступны.

Примечание: Избегайте вызова winId() для QQuickWidget. Эта функция запускает создание нативного окна, что приводит к снижению производительности и возможным проблемам с отрисовкой. Цель QQuickWidget — отрисовывать Quick-сцены без отдельного нативного окна, поэтому следует всегда избегать приведения его к нативному виджету.

Граф сцены и персистентность контекста

QQuickWidget учитывает QQuickWindow::isPersistentSceneGraph(), что означает, что приложения могут решать — вызывая QQuickWindow::setPersistentSceneGraph() для окна, возвращённого функцией quickWindow() — позволять узлам графа сцены и другим ресурсам Qt Quick сцены быть освобождёнными всякий раз, когда виджет становится скрытым. По умолчанию персистентность включена, как и в QQuickWindow.

При работе с OpenGL-бекендом графа сцены, QQuickWindow предлагает возможность отключить персистентные OpenGL-контексты. Это свойство в настоящее время игнорируется QQuickWidget, и контекст всегда персистентный. Таким образом, OpenGL-контекст не уничтожается при скрытии виджета. Контекст уничтожается только при уничтожении виджета или при переприкреплении виджета в иерархию дочерних элементов другого виджета верхнего уровня. Однако некоторые приложения, особенно те, которые имеют собственные графические ресурсы из-за выполнения пользовательской отрисовки OpenGL в сцене Qt Quick, могут пожелать отключить последнее, поскольку они могут не быть готовы обрабатывать потерю контекста при перемещении QQuickWidget в другое окно. Такие приложения могут установить атрибут QCoreApplication::AA_ShareOpenGLContexts. Для обсуждения деталей инициализации и очистки ресурсов обратитесь к документации QOpenGLWidget.

Примечание: QQuickWidget предоставляет менее тонкую настройку внутреннего OpenGL-контекста, чем QOpenGLWidget, и существуют незначительные различия, в частности, что отключение персистентного графа сцены приведёт к уничтожению контекста при изменении окна независимо от наличия QCoreApplication::AA_ShareOpenGLContexts.

Ограничения

Размещение других виджетов под QQuickWidget и придание ему прозрачности не приведёт к ожидаемым результатам: виджеты, расположенные под ним, не будут видны. Это связано с тем, что на практике QQuickWidget отрисовывается перед всеми другими обычными виджетами, не использующими OpenGL, поэтому решения с прозрачностью невозможны. Другие типы макетов, например, размещение виджетов поверх QQuickWidget, будут работать как ожидается.

В абсолютно необходимых случаях это ограничение можно преодолеть, установив атрибут Qt::WA_AlwaysStackOnTop для QQuickWidget. Имейте в виду, что это нарушает порядок расположения в стеке. Например, не удастся разместить другие виджеты поверх QQuickWidget, поэтому его следует использовать только в ситуациях, когда требуется полупрозрачный QQuickWidget с другими виджетами, видимыми под ним.

Это ограничение применимо только в том случае, если под QQuickWidget в том же окне есть другие виджеты. Делание окна полупрозрачным, с другими приложениями и рабочим столом, видимыми на заднем плане, выполняется традиционным способом: установите Qt::WA_TranslucentBackground для окна верхнего уровня, запросите альфа-канал и измените цвет очистки графа сцены Qt Quick на Qt::transparent через setClearColor().

Поддержка при отсутствии OpenGL

Помимо OpenGL, бэкенд Qt Quick также поддерживает QQuickWidget. Однако другие бэкенды, например OpenVG, несовместимы, и попытка создать QQuickWidget приведёт к проблемам.

Обработка клавиши Tab

При нажатии клавиши [TAB] элемент внутри QQuickWidget получает фокус. Если этот элемент может обрабатывать нажатие клавиши [TAB], фокус изменится соответствующим образом внутри элемента; в противном случае фокус получит следующий виджет в цепочке фокуса.

См. также Выставление атрибутов C++ типов в QML, Пример виджетов Qt Quick и QQuickView.

Документация типов членов

перечисление QQuickWidget::ResizeMode

Это перечисление определяет, как масштабировать представление.

перечисление QQuickWidget::Status

Определяет состояние загрузки QQuickWidget.

Документация функций членов

QQuickWidget::QQuickWidget(const QUrl &source, QWidget *parent = nullptr)

Создаёт QQuickWidget с заданным QML source и parent. Значение по умолчанию для parent — 0.

QQuickWidget::QQuickWidget(QQmlEngine *engine, QWidget *parent)

Создаёт QQuickWidget с заданным QML engine и parent.

Примечание: в этом случае QQuickWidget не владеет объектом engine; за его уничтожение отвечает вызывающий код. Если engine удалён до представления, status() вернёт QQuickWidget::Error.

См. также Status, status() и errors().

QQuickWidget::QQuickWidget(QWidget *parent = nullptr)

Создаёт QQuickWidget с заданным parent. Значение по умолчанию для parent — 0.

void QQuickWidget::sceneGraphError(QQuickWindow::SceneGraphError error, const QString &message)

Этот сигнал излучается, когда во время инициализации графа сцены произошла ошибка.

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

Этот сигнал будет излучаться из потока GUI.

См. также QQuickWindow::sceneGraphError().

[slot] void QQuickWidget::setSource(const QUrl &url)

Устанавливает исходный адрес в url, загружает компонент QML и инициализирует его.

Убедитесь, что предоставленный URL-адрес полный и правильный, в частности, используйте QUrl::fromLocalFile(), при загрузке файла из локальной файловой системы.

Вызов этого метода несколько раз с одним и тем же URL-адресом приведет к повторной инициализации компонента QML.

Примечание: Метод-сеттер для свойства source.

См. также source().

[signal] void QQuickWidget::statusChanged(QQuickWidget::Status status)

Этот сигнал излучается, когда текущий статус компонента изменяется.

Примечание: Сигнал уведомления для свойства status.

[override virtual] QQuickWidget::~QQuickWidget()

Уничтожает QQuickWidget.

[override virtual protected] void QQuickWidget::dragEnterEvent(QDragEnterEvent *e)

Переопределяет: QWidget::dragEnterEvent(QDragEnterEvent *event).

[override virtual protected] void QQuickWidget::dragLeaveEvent(QDragLeaveEvent *e)

Переопределяет: QWidget::dragLeaveEvent(QDragLeaveEvent *event).

[override virtual protected] void QQuickWidget::dragMoveEvent(QDragMoveEvent *e)

Переопределяет: QWidget::dragMoveEvent(QDragMoveEvent *event).

[override virtual protected] void QQuickWidget::dropEvent(QDropEvent *e)

Переопределяет: QWidget::dropEvent(QDropEvent *event).

QQmlEngine *QQuickWidget::engine() const

Возвращает указатель на QQmlEngine, используемый для инициализации компонентов QML.

QList<QQmlError> QQuickWidget::errors() const

Возвращает список ошибок, возникших во время последней компиляции или операции создания. Если статус не Error, возвращается пустой список.

См. также status.

[override virtual protected] bool QQuickWidget::event(QEvent *e)

Переопределяет: QWidget::event(QEvent *event).

[override virtual protected] void QQuickWidget::focusInEvent(QFocusEvent *event)

Переопределяет: QWidget::focusInEvent(QFocusEvent *event).

[override virtual protected] bool QQuickWidget::focusNextPrevChild(bool next)

Переопределяет: QWidget::focusNextPrevChild(bool next).

[override virtual protected] void QQuickWidget::focusOutEvent(QFocusEvent *event)

Переопределяет: QWidget::focusOutEvent(QFocusEvent *event).

QSurfaceFormat QQuickWidget::format() const

Возвращает фактический формат поверхности.

Если виджет еще не показан, возвращается запрошенный формат.

См. также setFormat().

QImage QQuickWidget::grabFramebuffer() const

Отображает кадр и считывает его обратно в изображение.

Примечание: Это потенциально дорогостоящая операция.

[override virtual protected] void QQuickWidget::hideEvent(QHideEvent *)

Переопределяет: QWidget::hideEvent(QHideEvent *event).

QSize QQuickWidget::initialSize() const

Возвращает начальный размер корневого объекта.

Если resizeMode равен SizeRootObjectToView, корневой объект будет изменён на размер представления. Эта функция возвращает размер корневого объекта до его изменения размера.

[override virtual protected] void QQuickWidget::keyPressEvent(QKeyEvent *e)

Переопределяет: QWidget::keyPressEvent(QKeyEvent *event).

[override virtual protected] void QQuickWidget::keyReleaseEvent(QKeyEvent *e)

Переопределяет: QWidget::keyReleaseEvent(QKeyEvent *event).

[override virtual protected] void QQuickWidget::mouseDoubleClickEvent(QMouseEvent *e)

Переопределяет: QWidget::mouseDoubleClickEvent(QMouseEvent *event).

[override virtual protected] void QQuickWidget::mouseMoveEvent(QMouseEvent *e)

Переопределяет: QWidget::mouseMoveEvent(QMouseEvent *event).

[override virtual protected] void QQuickWidget::mousePressEvent(QMouseEvent *e)

Переопределяет: QWidget::mousePressEvent(QMouseEvent *event).

[override virtual protected] void QQuickWidget::mouseReleaseEvent(QMouseEvent *e)

Переопределяет: QWidget::mouseReleaseEvent(QMouseEvent *event).

[override virtual protected] void QQuickWidget::paintEvent(QPaintEvent *event)

Переопределяет: QWidget::paintEvent(QPaintEvent *event).

[since 5.5] QQuickWindow *QQuickWidget::quickWindow() const

Возвращает внеэкранное QQuickWindow, используемое этим виджетом для управления рендерингом Qt Quick. Это полезно, если вы хотите использовать API QQuickWindow, которые в настоящее время не доступны QQuickWidget, например, подключение к сигналу QQuickWindow::beforeRendering() для отрисовки нативного OpenGL-контента под собственным рендерингом Qt Quick.

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

Предупреждение: Внеэкранное окно может быть удалено (и пересоздано) в течение жизненного цикла QQuickWidget, особенно когда виджет перемещается в другое QQuickWindow. Если вам нужно узнать, когда окно было заменено, подключитесь к его сигналу destroyed().

Эта функция была добавлена в Qt 5.5.

QQmlContext *QQuickWidget::rootContext() const

Эта функция возвращает корень иерархии контекстов. Каждый компонент QML инициализируется в QQmlContext. QQmlContext необходимы для передачи данных в компоненты QML. В QML контексты организованы иерархически, и эта иерархия управляется QQmlEngine.

QQuickItem *QQuickWidget::rootObject() const

Возвращает корневый элемент представления. Может быть нулевым, когда setSource() не был вызван, если он был вызван с некорректным кодом QtQuick или в то время, когда содержимое QtQuick создается.

void QQuickWidget::setClearColor(const QColor &color)

Устанавливает цвет очистки color. По умолчанию это непрозрачный цвет.

Для получения полупрозрачного QQuickWidget, вызовите эту функцию со значением color, установленным в Qt::transparent, установите атрибут виджета Qt::WA_TranslucentBackground для окна верхнего уровня и запросите альфа-канал через setFormat().

См. также QQuickWindow::setColor().

void QQuickWidget::setFormat(const QSurfaceFormat &format)

Устанавливает формат поверхности format для контекста и внеэкранной поверхности, используемых этим виджетом.

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

См. также QWindow::setFormat(), QWindow::format() и format().

[override virtual protected] void QQuickWidget::showEvent(QShowEvent *)

Переопределяет: QWidget::showEvent(QShowEvent *event).

QUrl QQuickWidget::source() const

Возвращает URL источника, если он задан.

Примечание: Функция-геттер для свойства source.

См. также setSource().

[override virtual protected] void QQuickWidget::wheelEvent(QWheelEvent *e)

Переопределяет: QWidget::wheelEvent(QWheelEvent *event).