Класс QQuickWidget

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

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

Типы public

Свойства

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

• 59 свойств унаследованных от QWidget
• 1 свойство унаследованное от QObject

Функции public

• 219 функций public, унаследованных от QWidget
• 34 функции public, унаследованные от QObject
• 14 функций public, унаследованных от QPaintDevice

Слот public

• 19 слотов public, унаследованных от QWidget
• 1 слот public, унаследованный от QObject

Сигналы

• 3 сигнала, унаследованные от QWidget
• 2 сигнала, унаследованные от QObject

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

• 35 защищённых функций, унаследованных от QWidget
• 9 защищённых функций, унаследованных от QObject
• 1 защищённая функция, унаследованная от QPaintDevice

Дополнительные унаследованные члены

• 1 общедоступная переменная, унаследованная от QWidget
• 1 общедоступная переменная, унаследованная от QObject
• 7 статические общедоступные члены, унаследованные от QWidget
• 10 статических общедоступных членов, унаследованные от QObject
• 35 защищённые функции, унаследованные от QWidget
• 9 защищённые функции, унаследованные от QObject
• 1 защищённая функция, унаследованная от QPaintDevice
• 1 защищённый слот, унаследованный от QWidget
• 2 защищённые переменные, унаследованные от QObject
• 1 защищённый тип, унаследованный от QPaintDevice

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

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

Это обертка для 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. Это естественным образом может привести к небольшой потере производительности.

Примечание: Использование 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, QQuickWidget также поддерживает software бэкенд Qt Quick. Однако другие бэкенды, например, Direct 3D 12, несовместимы, и попытка создать QQuickWidget приведет к проблемам.

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

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

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

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

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

Это перечисление определяет способ изменения размера представления.

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

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

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

QQuickWidget::QQuickWidget(QWidget *parent = nullptr)

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

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

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

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

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

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

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

[override virtual] QQuickWidget::~QQuickWidget()

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

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

Переопределено из QWidget::dragEnterEvent().

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

Переопределено из QWidget::dragLeaveEvent().

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

Переопределено из QWidget::dragMoveEvent().

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

Переопределено из QWidget::dropEvent().

QQmlEngine *QQuickWidget::engine() const

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

QList<QQmlError> QQuickWidget::errors() const

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

См. также status.

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

Переопределено из QWidget::event().

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

Переопределено из QWidget::focusInEvent().

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

Переопределено из QWidget::focusNextPrevChild().

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

Переопределено из QWidget::focusOutEvent().

QSurfaceFormat QQuickWidget::format() const

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

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

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

QImage QQuickWidget::grabFramebuffer() const

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

Примечание: Эта операция может быть ресурсоёмкой.

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

Переопределено из QWidget::hideEvent().

QSize QQuickWidget::initialSize() const

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

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

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

Переопределено из QWidget::keyPressEvent().

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

Переопределено из QWidget::keyReleaseEvent().

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

Переопределено из QWidget::mouseDoubleClickEvent().

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

Переопределено из QWidget::mouseMoveEvent().

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

Переопределено из QWidget::mousePressEvent().

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

Переопределено из QWidget::mouseReleaseEvent().

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

Переопределено из QWidget::paintEvent().

QQuickWindow *QQuickWidget::quickWindow() const

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

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

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

QQmlContext *QQuickWidget::rootContext() const

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

QQuickItem *QQuickWidget::rootObject() const

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

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

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

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

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

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

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().

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

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

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

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

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

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

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

Переопределено из QWidget::showEvent().

QUrl QQuickWidget::source() const

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

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

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

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

Этот сигнал генерируется при изменении текущего status компонента.

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

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

Переопределено из QWidget::wheelEvent().