Класс QQuickItem

Класс QQuickItem предоставляет самые базовые визуальные элементы в Qt Quick. Подробнее...

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

Типы публичного доступа

Свойства

Публичные функции

Public Slots

Signals

Protected Functions

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

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

Все визуальные элементы в Qt Quick наследуются от QQuickItem. Хотя экземпляр QQuickItem не имеет визуального отображения, он определяет все атрибуты, общие для визуальных элементов, такие как положение x и y, ширина и высота, привязка и поддержка обработки ключевых событий.

Вы можете наследовать от QQuickItem, чтобы предоставить свой собственный пользовательский визуальный элемент, который наследует эти функции.

Пользовательские элементы сцены

Все визуальные QML-элементы отрисовываются с использованием графического дерева, по умолчанию реализованного как высокопроизводительный низкоуровневый рендеринг, тесно связанный с ускоренными графическими API, такими как OpenGL, Vulkan, Metal или Direct 3D. Подклассы QQuickItem могут добавлять свой собственный пользовательский контент в графическое дерево, установив флаг QQuickItem::ItemHasContents и переопределяя функцию QQuickItem::updatePaintNode().

Предупреждение: Крайне важно, чтобы графические операции и взаимодействие с графическим деревом происходили исключительно в потоке рендеринга, в основном во время вызова updatePaintNode(). Лучшее правило — использовать только классы с префиксом «QSG» внутри функции QQuickItem::updatePaintNode().

Примечание: Все классы с префиксом QSG должны использоваться только в потоке рендеринга графического дерева. Дополнительную информацию см. в разделе Графическое дерево и рендеринг.

Обработка графических ресурсов

Предпочтительный способ обработки очистки графических ресурсов, используемых в графическом дереве, — это полагаться на автоматическую очистку узлов. QSGNode, возвращаемый из QQuickItem::updatePaintNode(), автоматически удаляется в правильном потоке и в нужное время. Деревья QSGNode управляются с помощью QSGNode::OwnedByParent, который устанавливается по умолчанию. Таким образом, для большинства пользовательских элементов графического дерева дополнительных действий не потребуется.

Реализации, которые хранят графические ресурсы за пределами дерева узлов, такие как элемент, реализующий QQuickItem::textureProvider(), должны позаботиться об их правильной очистке в зависимости от того, как элемент используется в QML. Ситуации, которые нужно обработать:

• Графическое дерево становится недействительным; это может произойти в зависимости от платформы и конфигурации QQuickWindow, когда окно скрывается с помощью QQuickWindow::hide() или когда оно закрывается. Если класс элемента реализует слот, названный slot, этот слот будет вызван в потоке рендеринга, пока поток GUI заблокирован. Это эквивалентно подключению к QQuickWindow::sceneGraphInvalidated(). При рендеринге через OpenGL контекст OpenGL окна этого элемента будет связан при вызове этого слота. Исключением является случай, если родной OpenGL был уничтожен вне контроля Qt, например, через EGL_CONTEXT_LOST.
• Элемент удаляется из сцены; если элемент удаляется из сцены, например, потому что его родитель был изменён на null или элемент находится в другом окне, QQuickItem::releaseResources() будет вызван в потоке GUI. Для планирования очистки ресурсов рендеринга следует использовать QQuickWindow::scheduleRenderJob().
• Элемент удаляется; когда выполняется деструктор элемента, он должен удалить все графические ресурсы, которыми он обладает. Если ни одно из двух условий выше не выполнено, элемент будет частью окна, и можно использовать QQuickWindow::scheduleRenderJob для планирования их очистки. Если реализация игнорирует вызов QQuickItem::releaseResources(), элемент во многих случаях больше не будет иметь доступ к QQuickWindow и, следовательно, не сможет планировать очистку.

При планировании очистки графических ресурсов с помощью QQuickWindow::scheduleRenderJob(), необходимо использовать либо QQuickWindow::BeforeSynchronizingStage, либо QQuickWindow::AfterSynchronizingStage. Стадия синхронизации — это момент, когда структура сцены изменяется в результате изменений в дереве QML. Если очистка запланирована в другое время, могут возникнуть ситуации, когда другие части структуры сцены будут ссылаться на только что удалённые объекты, поскольку эти части не были обновлены.

Примечание: Использование QObject::deleteLater() для очистки графических ресурсов категорически не рекомендуется, так как это приведет к выполнению операции delete в произвольный момент времени, и неизвестно, будет ли связан контекст OpenGL во время удаления.

Пользовательские элементы QPainter

QQuickItem предоставляет подкласс QQuickPaintedItem, который позволяет пользователям отрисовывать содержимое с помощью QPainter.

Предупреждение: Использование QQuickPaintedItem использует косвенную 2D-поверхность для отрисовки содержимого, используя программную растризацию, поэтому отрисовка является двухэтапной операцией. Сначала растрируется поверхность, затем отрисовывается поверхность. Использование API структуры сцены напрямую всегда значительно быстрее.

Анимации поведения

Если ваш элемент использует тип Behavior для определения анимаций изменений свойств, всегда используйте QObject::setProperty(), QQmlProperty() или QMetaProperty::write() при необходимости изменения этих свойств из C++. Это гарантирует, что движок QML знает о изменении свойства. В противном случае движок не сможет выполнить запрошенную анимацию. Обратите внимание, что эти функции несут небольшую нагрузку на производительность. Более подробная информация доступна в разделе Доступ к членам типа QML объекта из C++.

См. также QQuickWindow и QQuickPaintedItem.

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

enum QQuickItem::Flagflags QQuickItem::Flags

Этот тип перечисления используется для задания различных свойств элемента.

Тип Flags — это псевдоним для QFlags<Flag>. Он хранит логическое ИЛИ комбинацию значений Flag.

См. также setFlag(), setFlags(), и flags().

enum QQuickItem::ItemChange

Используется совместно с QQuickItem::itemChange(), чтобы уведомить элемент о определённых типах изменений.

enum QQuickItem::TransformOrigin

Управляет точкой, относительно которой применяются простые преобразования, такие как масштабирование.

См. также transformOrigin() и setTransformOrigin().

// Label.qml
import QtQuick 2.0

Item {
    property alias icon: image.source
    property alias label: text.text
    implicitWidth: text.implicitWidth + image.implicitWidth
    implicitHeight: Math.max(text.implicitHeight, image.implicitHeight)
    Image { id: image }
    Text {
        id: text
        wrapMode: Text.Wrap
        anchors.left: image.right; anchors.right: parent.right
        anchors.verticalCenter: parent.verticalCenter
    }
}

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        focus: true

        TextInput {
            id: input
            focus: true
        }
    }
}

import QtQuick 2.0

Rectangle {
    width: 100; height: 100

    FocusScope {
        id: scope

        TextInput {
            id: input
            focus: true
        }
    }
}

Rectangle {
    width: 100; height: 100

    TextInput {
          id: input
          focus: true
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        opacity: 0.5
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Rectangle {
    color: "blue"
    width: 100; height: 100
    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        rotation: 30
    }
}

import QtQuick 2.0

Rectangle {
    color: "blue"
    width: 100; height: 100

    Rectangle {
        color: "green"
        width: 25; height: 25
    }

    Rectangle {
        color: "red"
        x: 25; y: 25; width: 50; height: 50
        scale: 1.4
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        z: 1
        color: "red"
        width: 100; height: 100
    }
    Rectangle {
        color: "blue"
        x: 50; y: 50; width: 100; height: 100
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

Item {
    Rectangle {
        color: "red"
        width: 100; height: 100
        Rectangle {
            z: -1
            color: "blue"
            x: 50; y: 50; width: 100; height: 100
        }
    }
}

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

QQuickItem::QQuickItem(QQuickItem *parent = nullptr)

Конструирует QQuickItem с указанным parent.

parent будет использоваться как визуальный родитель, так и родительский элемент QObject.

[slot] void QQuickItem::update()

Планирует вызов updatePaintNode() для данного элемента.

Вызов QQuickItem::updatePaintNode() всегда происходит, если элемент отображается в QQuickWindow.

Только элементы, которые указывают QQuickItem::ItemHasContents, могут вызывать QQuickItem::update().

[signal] void QQuickItem::windowChanged(QQuickWindow *window)

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

[override virtual] QQuickItem::~QQuickItem()

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

bool QQuickItem::acceptHoverEvents() const

Возвращает значение, указывающее, принимаются ли события наведения курсора этим элементом.

Значение по умолчанию — false.

Если это значение равно false, элемент не будет получать события наведения курсора через функции hoverEnterEvent(), hoverMoveEvent() и hoverLeaveEvent().

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

[since 5.10] bool QQuickItem::acceptTouchEvents() const

Возвращает значение, указывающее, принимаются ли события касания этим элементом.

Значение по умолчанию — false.

Если это значение равно false, элемент не будет получать события касания через функцию touchEvent().

Функция была введена в Qt 5.10.

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

Qt::MouseButtons QQuickItem::acceptedMouseButtons() const

Возвращает кнопки мыши, принимаемые этим элементом.

Значение по умолчанию — Qt::NoButton, то есть кнопки мыши не принимаются.

Если элемент не принимает кнопку мыши для определенного события мыши, это событие не будет передано элементу и будет передано следующему элементу в иерархии элементов.

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

QQuickItem *QQuickItem::childAt(qreal x, qreal y) const

Возвращает первый видимый дочерний элемент, найденный в точке (x, y) в системе координат этого элемента.

Возвращает nullptr , если такого элемента нет.

Примечание: К этой функции можно обратиться через систему метаобъектов и из QML. См. Q_INVOKABLE.

QList<QQuickItem *> QQuickItem::childItems() const

Возвращает потомков этого элемента.

[virtual protected] bool QQuickItem::childMouseEventFilter(QQuickItem *item, QEvent *event)

Переопределите этот метод для фильтрации событий указателя, которые получает потомки этого элемента.

Этот метод будет вызван только в том случае, если filtersChildMouseEvents() равно true.

Возвратите true , если указанное событие event не должно передаваться указанному дочернему элементу item, и false в противном случае.

Примечание: Несмотря на название, эта функция фильтрует все экземпляры QPointerEvent во время доставки всем потомкам (обычно события мыши, касания и планшета). При переопределении этой функции в подклассе рекомендуется писать код обработки событий общего назначения, используя только доступные методы в QPointerEvent. В качестве альтернативы можно включить event->type() и/или event->device()->type() для обработки различных типов событий различными способами.

Примечание: Фильтрация — всего лишь один из способов распределения ответственности в случае неоднозначности жестов (например, при нажатии вы не знаете, будет ли нажатие одиночным или перетаскиванием). Другой способ — вызвать QPointerEvent::addPassiveGrabber() при нажатии, чтобы неэксклюзивно отслеживать прогресс QEventPoint. В любом случае, элемент или обработчик указателя, отслеживающий, может впоследствии захватить исключительное управление, когда станет ясно, что жест соответствует ожидаемому шаблону.

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

[override virtual protected] void QQuickItem::classBegin()

Переопределяет: QQmlParserStatus::classBegin().

Подклассы должны вызывать базовый метод перед добавлением собственных действий для выполнения в classBegin.

[override virtual protected] void QQuickItem::componentComplete()

Переопределяет: QQmlParserStatus::componentComplete().

Производные классы должны вызывать метод базового класса перед добавлением собственных действий, выполняемых при componentComplete.

[virtual] bool QQuickItem::contains(const QPointF &point) const

Возвращает true, если данный элемент содержит point, заданный в локальных координатах; в противном случае возвращает false.

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

Обратите внимание, что этот метод обычно используется для проверки, находится ли элемент под курсором мыши, и поэтому его реализация должна быть максимально лёгкой.

Примечание: Этот метод может быть вызван через механизм метаобъектов и из QML. См. Q_INVOKABLE.

QCursor QQuickItem::cursor() const

Возвращает форму курсора для данного элемента.

Курсор мыши примет эту форму, когда он будет над этим элементом, если не установлен курсор-переопределение. Список предопределённых объектов курсора см. в списке предопределённых объектов курсора для ряда полезных форм.

Если форма курсора не установлена, возвращается курсор с формой Qt::ArrowCursor, однако может отображаться другая форма курсора, если перекрывающий элемент имеет корректный курсор.

См. также setCursor() и unsetCursor().

[virtual protected] void QQuickItem::dragEnterEvent(QDragEnterEvent *event)

Обработчик этого события можно переопределить в подклассе для получения событий drag-enter для элемента. Информация о событии предоставляется параметром event.

События перетаскивания и падения предоставляются только в том случае, если для данного элемента установлен флаг ItemAcceptsDrops.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

См. также Перетаскивание и Перетаскивание и сбрасывание.

[virtual protected] void QQuickItem::dragLeaveEvent(QDragLeaveEvent *event)

Обработчик этого события можно переопределить в подклассе для получения событий drag-leave для элемента. Информация о событии предоставляется параметром event.

События перетаскивания и падения предоставляются только в том случае, если для данного элемента установлен флаг ItemAcceptsDrops.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

См. также Перетаскивание и Перетаскивание и сбрасывание.

[virtual protected] void QQuickItem::dragMoveEvent(QDragMoveEvent *event)

Обработчик этого события можно переопределить в подклассе для получения событий drag-move для элемента. Информация о событии предоставляется параметром event.

События перетаскивания и падения предоставляются только в том случае, если для данного элемента установлен флаг ItemAcceptsDrops.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

См. также Перетаскивание и Перетаскивание и сбрасывание.

[virtual protected] void QQuickItem::dropEvent(QDropEvent *event)

Обработчик этого события можно переопределить в подклассе для получения событий drop для элемента. Информация о событии предоставляется параметром event.

События перетаскивания и падения предоставляются только в том случае, если для данного элемента установлен флаг ItemAcceptsDrops.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

См. также Перетаскивание и Перетаскивание и сбрасывание.

[override virtual protected] bool QQuickItem::event(QEvent *ev)

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

bool QQuickItem::filtersChildMouseEvents() const

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

Если и этот элемент, и дочерний элемент имеют acceptTouchEvents() true, то при возникновении сенсорного взаимодействия этот элемент будет фильтровать сенсорное событие. Но если ни этот элемент, ни дочерний элемент не могут обрабатывать сенсорные события, childMouseEventFilter() будет вызван с синтезированным событием мыши.

См. также setFiltersChildMouseEvents() и childMouseEventFilter().

QQuickItem::Flags QQuickItem::flags() const

Возвращает флаги элемента для данного элемента.

См. также setFlags() и setFlag().

[virtual protected] void QQuickItem::focusInEvent(QFocusEvent *)

Обработчик этого события можно переопределить в подклассе для получения событий получения фокуса для элемента. Информация о событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

Если вы переопределяете эту функцию, вы должны вызвать реализацию базового класса.

[virtual protected] void QQuickItem::focusOutEvent(QFocusEvent *)

Обработчик этого события можно переопределить в подклассе для получения событий потери фокуса для элемента. Информация о событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

void QQuickItem::forceActiveFocus()

Принудительно активирует фокус на элементе.

Этот метод устанавливает фокус на элемент и гарантирует, что все предковые объекты FocusScope в иерархии объектов также получат фокус.

Причина изменения фокуса будет Qt::OtherFocusReason. Используйте перегруженный метод, чтобы указать причину изменения фокуса для лучшей обработки изменения фокуса.

Примечание: Этот метод может быть вызван через механизм метаобъектов и из QML. См. Q_INVOKABLE.

См. также activeFocus.

[since 5.1] void QQuickItem::forceActiveFocus(Qt::FocusReason reason)

Это перегруженный метод.

Принудительно активирует фокус на элементе с указанной причиной reason.

Этот метод устанавливает фокус на элемент и гарантирует, что все предковые объекты FocusScope в иерархии объектов также получат фокус.

Примечание: Этот метод может быть вызван через механизм метаобъектов и из QML. См. Q_INVOKABLE.

Этот метод был добавлен в Qt 5.1.

См. также activeFocus и Qt::FocusReason.

[virtual protected, since 6.0] void QQuickItem::geometryChange(const QRectF &newGeometry, const QRectF &oldGeometry)

Этот метод вызывается для обработки изменений геометрии этого элемента от oldGeometry до newGeometry. Если две геометрии одинаковы, ничего не происходит.

Производные классы должны вызывать метод базового класса в своей реализации.

Этот метод был добавлен в Qt 6.0.

QSharedPointer<QQuickItemGrabResult> QQuickItem::grabToImage(const QSize &targetSize = QSize())

Захватывает элемент в изображение в памяти.

Захват происходит асинхронно, и сигнал QQuickItemGrabResult::ready() излучается, когда захват завершён.

Используйте targetSize для задания размера целевого изображения. По умолчанию результат будет иметь тот же размер, что и элемент.

Если захват не может быть инициирован, функция возвращает null.

Примечание: Эта функция будет рендерить элемент на внеэкранной поверхности и копировать эту поверхность из памяти графического процессора в память центрального процессора, что может быть довольно дорогостоящим. Для «живого» предварительного просмотра используйте слои или ShaderEffectSource.

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

[protected] bool QQuickItem::heightValid() const

Возвращает значение, указывающее, была ли высота свойства явно задана.

[virtual protected] void QQuickItem::hoverEnterEvent(QHoverEvent *event)

Этот обработчик событий можно переопределить в подклассе для получения событий входа курсора в элемент. Информация об событии предоставляется параметром event.

События наведения курсора предоставляются только если acceptHoverEvents() имеет значение true.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не хотите принимать событие, вызовите event->ignore().

[virtual protected] void QQuickItem::hoverLeaveEvent(QHoverEvent *event)

Этот обработчик событий можно переопределить в подклассе для получения событий выхода курсора из элемента. Информация об событии предоставляется параметром event.

События наведения курсора предоставляются только если acceptHoverEvents() имеет значение true.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не хотите принимать событие, вызовите event->ignore().

[virtual protected] void QQuickItem::hoverMoveEvent(QHoverEvent *event)

Этот обработчик событий можно переопределить в подклассе для получения событий перемещения курсора над элементом. Информация об событии предоставляется параметром event.

События наведения курсора предоставляются только если acceptHoverEvents() имеет значение true.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не хотите принимать событие, вызовите event->ignore().

qreal QQuickItem::implicitWidth() const

Возвращает ширину элемента, которая подразумевается другими свойствами, определяющими содержимое.

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

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

[virtual protected] void QQuickItem::inputMethodEvent(QInputMethodEvent *event)

Этот обработчик событий можно переопределить в подклассе для получения событий ввода для элемента. Информация об событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не хотите принимать событие, вызовите event->ignore().

[virtual] QVariant QQuickItem::inputMethodQuery(Qt::InputMethodQuery query) const

Этот метод актуален только для элементов ввода.

Если этот элемент является элементом ввода, этот метод должен быть переопределён для возвращения соответствующих флагов метода ввода для данного query.

См. также QWidget::inputMethodQuery().

[since 5.7] bool QQuickItem::isAncestorOf(const QQuickItem *child) const

Возвращает true если этот элемент является родителем child (т.е., если этот элемент — родитель child или один из предков child).

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

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

[protected] bool QQuickItem::isComponentComplete() const

Возвращает true, если построение компонента QML завершено; в противном случае возвращает false.

Часто желательно отложить некоторую обработку до завершения компонента.

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

bool QQuickItem::isFocusScope() const

Возвращает true, если этот элемент является областью фокуса, и false в противном случае.

[virtual] bool QQuickItem::isTextureProvider() const

Возвращает true, если этот элемент является поставщиком текстур. По умолчанию возвращает false.

Эта функция может быть вызвана из любого потока.

[virtual protected] void QQuickItem::itemChange(QQuickItem::ItemChange change, const QQuickItem::ItemChangeData &value)

Вызывается, когда для этого элемента происходит событие change.

value содержит дополнительную информацию, относящуюся к изменению, если применимо.

Если вы переопределяете этот метод в подклассе, обязательно вызовите

QQuickItem::itemChange(change, value);

обычно в конце вашей реализации, чтобы гарантировать, что сигнал windowChanged() будет выпущен.

bool QQuickItem::keepMouseGrab() const

Возвращает значение, указывающее, следует ли сохранить захват мыши этим элементом.

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

bool QQuickItem::keepTouchGrab() const

Возвращает значение, указывающее, следует ли сохранить захват касаний этим элементом.

См. также setKeepTouchGrab() и keepMouseGrab().

[virtual protected] void QQuickItem::keyPressEvent(QKeyEvent *event)

Этот обработчик событий можно переопределить в подклассе для получения событий нажатия клавиш для элемента. Информация об событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не хотите принимать событие, вызовите event->ignore().

[virtual protected] void QQuickItem::keyReleaseEvent(QKeyEvent *event)

Этот обработчик событий можно переопределить в подклассе для получения событий отпускания клавиш для элемента. Информация об событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не хотите принимать событие, вызовите event->ignore().

[since 5.7] QPointF QQuickItem::mapFromGlobal(const QPointF &point) const

Преобразует указанную точку point в глобальной системе координат экрана в эквивалентную точку в системе координат этого элемента и возвращает преобразованную координату.

В преобразовании используются следующие свойства элемента: x, y, scale, rotation, transformOrigin и transform.

Например, это может быть полезно для добавления всплывающего окна к компоненту Qt Quick.

Примечание: Позиционирование окна выполняется менеджером окон, и это значение рассматривается только как подсказка. Поэтому фактическая позиция окна может отличаться от ожидаемой.

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

См. также Концепции - Визуальные координаты в Qt Quick.

QPointF QQuickItem::mapFromItem(const QQuickItem *item, const QPointF &point) const

Преобразует указанную точку point в системе координат элемента item в эквивалентную точку в системе координат этого элемента и возвращает преобразованную координату.

В преобразовании используются следующие свойства элемента: x, y, scale, rotation, transformOrigin и transform.

Если item равен 0, это преобразует point из системы координат сцены.

См. также Концепции - Визуальные координаты в Qt Quick.

QPointF QQuickItem::mapFromScene(const QPointF &point) const

Преобразует указанную точку point в системе координат сцены в эквивалентную точку в системе координат этого элемента и возвращает преобразованную координату.

В преобразовании используются следующие свойства элемента: x, y, scale, rotation, transformOrigin и transform.

См. также Концепции - Визуальные координаты в Qt Quick.

QRectF QQuickItem::mapRectFromItem(const QQuickItem *item, const QRectF &rect) const

Преобразует заданный прямоугольник rect в системе координат элемента item в эквивалентную прямоугольную область в системе координат этого элемента и возвращает преобразованное значение прямоугольника.

В преобразовании используются следующие свойства элемента: x, y, scale, rotation, transformOrigin и transform.

Если item равен 0, это преобразует rect из системы координат сцены.

См. также Концепции - Визуальные координаты в Qt Quick.

QRectF QQuickItem::mapRectFromScene(const QRectF &rect) const

Преобразует заданный прямоугольник rect в системе координат сцены в эквивалентную прямоугольную область в системе координат данного элемента и возвращает значение преобразованного прямоугольника.

Для преобразования используются следующие свойства элемента: x, y, масштаб, поворот, начало преобразования и преобразование.

См. также Концепции - Визуальные координаты в Qt Quick.

QRectF QQuickItem::mapRectToItem(const QQuickItem *item, const QRectF &rect) const

Преобразует заданный прямоугольник rect в системе координат данного элемента в эквивалентную прямоугольную область в системе координат элемента item и возвращает значение преобразованного прямоугольника.

Для преобразования используются следующие свойства элемента: x, y, масштаб, поворот, начало преобразования и преобразование.

Если item равен 0, это преобразование rect в систему координат сцены.

См. также Концепции - Визуальные координаты в Qt Quick.

QRectF QQuickItem::mapRectToScene(const QRectF &rect) const

Преобразует заданный прямоугольник rect в системе координат данного элемента в эквивалентную прямоугольную область в системе координат сцены и возвращает значение преобразованного прямоугольника.

Для преобразования используются следующие свойства элемента: x, y, масштаб, поворот, начало преобразования и преобразование.

См. также Концепции - Визуальные координаты в Qt Quick.

[since 5.7] QPointF QQuickItem::mapToGlobal(const QPointF &point) const

Преобразует заданную точку point в системе координат данного элемента в эквивалентную точку в глобальной системе координат экрана и возвращает преобразованную координату.

Для преобразования используются следующие свойства элемента: x, y, масштаб, поворот, начало преобразования и преобразование.

Например, это может быть полезно для добавления всплывающего окна к компоненту Qt Quick.

Примечание: Размещение окна выполняется менеджером окон, и это значение рассматривается только как подсказка. Таким образом, фактическое положение окна может отличаться от ожидаемого.

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

См. также Концепции - Визуальные координаты в Qt Quick.

QPointF QQuickItem::mapToItem(const QQuickItem *item, const QPointF &point) const

Преобразует заданную точку point в системе координат данного элемента в эквивалентную точку в системе координат элемента item и возвращает преобразованную координату.

Для преобразования используются следующие свойства элемента: x, y, масштаб, поворот, начало преобразования и преобразование.

Если item равен 0, это преобразование point в систему координат сцены.

См. также Концепции - Визуальные координаты в Qt Quick.

QPointF QQuickItem::mapToScene(const QPointF &point) const

Преобразует заданную точку point в системе координат данного элемента в эквивалентную точку в системе координат сцены и возвращает преобразованную координату.

Для преобразования используются следующие свойства элемента: x, y, масштаб, поворот, начало преобразования и преобразование.

См. также Концепции - Визуальные координаты в Qt Quick.

[virtual protected] void QQuickItem::mouseDoubleClickEvent(QMouseEvent *event)

Обработчик этого события может быть переопределен в подклассе для получения событий двойного щелчка мыши для элемента. Информация о событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не принимаете событие, вызовите event->ignore().

[virtual protected] void QQuickItem::mouseMoveEvent(QMouseEvent *event)

Обработчик этого события может быть переопределен в подклассе для получения событий перемещения мыши для элемента. Информация о событии предоставляется параметром event.

Для получения событий перемещения мыши предыдущее событие нажатия мыши должно быть принято (например, путем переопределения mousePressEvent() ) и acceptedMouseButtons() должно возвращать соответствующую кнопку мыши.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не принимаете событие, вызовите event->ignore().

[virtual protected] void QQuickItem::mousePressEvent(QMouseEvent *event)

Обработчик этого события может быть переопределен в подклассе для получения событий нажатия мыши для элемента. Информация о событии предоставляется параметром event.

Для получения событий нажатия мыши acceptedMouseButtons() должно возвращать соответствующую кнопку мыши.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не принимаете событие, вызовите event->ignore().

[virtual protected] void QQuickItem::mouseReleaseEvent(QMouseEvent *event)

Обработчик этого события может быть переопределен в подклассе для получения событий отпускания кнопки мыши для элемента. Информация о событии предоставляется параметром event.

Для получения событий отпускания кнопки мыши предыдущее событие нажатия мыши должно быть принято (например, путем переопределения mousePressEvent() ) и acceptedMouseButtons() должно возвращать соответствующую кнопку мыши.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределяете эту функцию. Если вы не принимаете событие, вызовите event->ignore().

[virtual protected] void QQuickItem::mouseUngrabEvent()

Этот обработчик событий может быть переопределен в подклассе для получения уведомления о том, что произошло событие отпускания захвата мыши для данного элемента.

QQuickItem *QQuickItem::nextItemInFocusChain(bool forward = true)

Возвращает элемент в цепочке фокуса, который находится рядом с этим элементом. Если forward равно true, или не указано, это следующий элемент в направлении вперёд. Если forward равно false, это следующий элемент в обратном направлении.

Примечание: Эта функция может быть вызвана через систему метаобъектов и из QML. См. Q_INVOKABLE.

void QQuickItem::polish()

Планирует событие полировки для данного элемента.

При обработке запроса графическим деревом будет вызван метод updatePolish() для данного элемента.

См. также updatePolish() и QQuickTest::qIsPolishScheduled().

[virtual protected] void QQuickItem::releaseResources()

Эта функция вызывается, когда элемент должен освободить графические ресурсы, которые ещё не управляются узлами, возвращаемыми из QQuickItem::updatePaintNode().

Это происходит, когда элемент собирается быть удалён из окна, в котором он ранее отображался. Гарантируется, что у элемента есть window, когда функция вызывается.

Функция вызывается в потоке GUI, а состояние потока рендеринга, если он используется, неизвестно. Объекты не должны удаляться напрямую, а вместо этого должны планироваться на очистку с использованием QQuickWindow::scheduleRenderJob().

См. также Обработка графических ресурсов.

QQuickItem *QQuickItem::scopedFocusItem() const

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

Возвращает nullptr если этот элемент не является областью фокуса.

void QQuickItem::setAcceptHoverEvents(bool enabled)

Если enabled равно true, это устанавливает элемент для приема событий наведения; в противном случае события наведения этим элементом не принимаются.

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

[since 5.10] void QQuickItem::setAcceptTouchEvents(bool enabled)

Если enabled имеет значение true, это задаёт элементу свойство принимать события касания; в противном случае, события касания этим элементом не принимаются.

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

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

void QQuickItem::setAcceptedMouseButtons(Qt::MouseButtons buttons)

Устанавливает принимаемые этим элементом кнопки мыши в buttons.

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

void QQuickItem::setCursor(const QCursor &cursor)

Устанавливает форму указателя cursor для этого элемента.

См. также cursor() и unsetCursor().

void QQuickItem::setFiltersChildMouseEvents(bool filter)

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

Если filter имеет значение true, childMouseEventFilter() будет вызываться при возникновении события указателя для дочернего элемента.

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

void QQuickItem::setFlag(QQuickItem::Flag flag, bool enabled = true)

Включает указанный flag для этого элемента, если enabled имеет значение true; если enabled имеет значение false, флаг отключается.

Эти флаги предоставляют различные подсказки для элемента; например, флаг ItemClipsChildrenToShape указывает, что все дочерние элементы этого элемента должны быть обрезаны, чтобы поместиться в область элемента.

void QQuickItem::setFlags(QQuickItem::Flags flags)

Включает указанные flags для этого элемента.

См. также flags() и setFlag().

void QQuickItem::setKeepMouseGrab(bool keep)

Устанавливает, нужно ли сохранить ввод мыши исключительно для этого элемента.

Это полезно для элементов, которые хотят захватить и удерживать взаимодействие мыши после выполнения предварительно определённого жеста. Например, элемент, заинтересованный в горизонтальном перемещении мыши, может установить keepMouseGrab в значение true, после того, как будет превышен определённый порог. После того, как keepMouseGrab установлен в значение true, фильтрующие элементы не будут реагировать на события мыши.

Если keep имеет значение false, фильтрующий элемент может захватить управление. Например, Flickable может попытаться захватить управление мышью, если обнаружит, что пользователь начал перемещать область просмотра.

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

void QQuickItem::setKeepTouchGrab(bool keep)

Устанавливает, нужно ли удерживать точки касания, захваченные этим элементом, исключительно для этого элемента.

Это полезно для элементов, которые хотят захватить и удерживать определённые точки касания после выполнения предварительно определённого жеста. Например, элемент, заинтересованный в горизонтальном перемещении точки касания, может установить setKeepTouchGrab в значение true, после того, как будет превышен определённый порог. После того, как setKeepTouchGrab установлен в значение true, фильтрующие элементы не будут реагировать на соответствующие точки касания.

Если keep имеет значение false, фильтрующий элемент может захватить управление. Например, Flickable может попытаться захватить управление точкой касания, если обнаружит, что пользователь начал перемещать область просмотра.

См. также keepTouchGrab() и setKeepMouseGrab().

[since 5.10] void QQuickItem::setSize(const QSizeF &size)

Устанавливает размер элемента в size.

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

См. также size, setWidth и setHeight.

[since 5.10] QSizeF QQuickItem::size() const

Возвращает размер элемента.

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

См. также setSize, width и height.

void QQuickItem::stackAfter(const QQuickItem *sibling)

Перемещает указанный элемент sibling в список дочерних элементов после этого элемента. Порядок дочерних элементов влияет как на визуальный порядок отображения, так и на порядок навигации по табу.

Предполагая, что значения z обоих элементов одинаковы, это приведёт к тому, что sibling будет отображаться ниже этого элемента.

Если оба элемента имеют activeFocusOnTab установленным в true, это также изменит порядок навигации по табу, при этом sibling получит фокус перед этим элементом.

Указанный sibling должен быть братом этого элемента; то есть они должны иметь одного общего родителя.

См. также Концепции - Визуальный родитель в Qt Quick.

void QQuickItem::stackBefore(const QQuickItem *sibling)

Перемещает указанный элемент sibling в список дочерних элементов перед этим элементом. Порядок дочерних элементов влияет как на визуальный порядок отображения, так и на порядок навигации по табу.

Предполагая, что значения z обоих элементов одинаковы, это приведёт к тому, что sibling будет отображаться выше этого элемента.

Если оба элемента имеют activeFocusOnTab установленным в true, это также изменит порядок навигации по табу, при этом sibling получит фокус после этого элемента.

Указанный sibling должен быть братом этого элемента; то есть они должны иметь одного общего родителя.

См. также Концепции - Визуальный родитель в Qt Quick.

[virtual] QSGTextureProvider *QQuickItem::textureProvider() const

Возвращает провайдер текстуры для элемента. Реализация по умолчанию возвращает nullptr.

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

[virtual protected] void QQuickItem::touchEvent(QTouchEvent *event)

Этот обработчик событий может быть переопределён в подклассе для получения событий касания для элемента. Информация о событии предоставляется параметром event.

Событие принимается по умолчанию, поэтому нет необходимости явно принимать событие, если вы переопределите эту функцию. Если вы не хотите принимать событие, вызовите event->ignore().

[virtual protected] void QQuickItem::touchUngrabEvent()

Этот обработчик событий может быть переопределён в подклассе для получения уведомления о том, что произошло событие отмены захвата касания для этого элемента.

void QQuickItem::unsetCursor()

Очищает форму указателя для этого элемента.

См. также cursor() и setCursor().

[protected] void QQuickItem::updateInputMethod(Qt::InputMethodQueries queries = Qt::ImQueryInput)

Уведомляет метод ввода о значениях обновлённых запросов, если необходимо. queries указывает изменённые атрибуты.

[virtual protected] QSGNode *QQuickItem::updatePaintNode(QSGNode *oldNode, QQuickItem::UpdatePaintNodeData *updatePaintNodeData)

Вызывается в потоке отрисовки, когда настаёт время синхронизировать состояние элемента с графическим деревом сцены.

Функция вызывается в результате QQuickItem::update(), если пользователь установил флаг QQuickItem::ItemHasContents для элемента.

Функция должна возвращать корень поддерева графического дерева сцены для этого элемента. Большинство реализаций возвращают один QSGGeometryNode, содержащий визуальное представление этого элемента. oldNode - узел, который был возвращён в прошлый раз, когда функция была вызвана. updatePaintNodeData предоставляет указатель на QSGTransformNode, связанный с этим QQuickItem.

QSGNode *MyItem::updatePaintNode(QSGNode *node, UpdatePaintNodeData *)
{
    QSGSimpleRectNode *n = static_cast<QSGSimpleRectNode *>(node);
    if (!n) {
        n = new QSGSimpleRectNode();
        n->setColor(Qt::red);
    }
    n->setRect(boundingRect());
    return n;
}

Основной поток блокируется во время выполнения этой функции, поэтому безопасно считывать значения из экземпляра QQuickItem и других объектов в главном потоке.

Если ни один вызов QQuickItem::updatePaintNode() не приводит к фактическим изменениям в графическом дереве сцены, например, QSGNode::markDirty() или добавление и удаление узлов, то реализация может принять решение не перерисовывать сцену, так как визуальный результат идентичен.

Предупреждение: Крайне важно, чтобы операции с графикой и взаимодействие с графическим деревом сцены происходили исключительно в потоке отрисовки, в основном во время вызова QQuickItem::updatePaintNode(). Лучшее правило - использовать только классы с префиксом "QSG" внутри функции QQuickItem::updatePaintNode().

Предупреждение: Эта функция вызывается в потоке отрисовки. Это означает, что любые QObjects или локальные хранилища потоков, созданные в ней, будут иметь связь с потоком отрисовки, поэтому будьте осторожны, когда делаете что-то помимо отрисовки в этой функции. Аналогично для сигналов, они будут испускаться в потоке отрисовки и, следовательно, часто будут доставляться через очереди соединений.

Примечание: Все классы с префиксом QSG должны использоваться только в потоке отрисовки графического дерева сцены. Дополнительную информацию см. в разделе Графическое дерево сцены и отрисовка.

См. также QSGMaterial, QSGGeometryNode, QSGGeometry, QSGFlatColorMaterial, QSGTextureMaterial, QSGNode::markDirty() и Обработка ресурсов графики.

[virtual protected] void QQuickItem::updatePolish()

Эта функция должна выполнять необходимую компоновку для данного элемента.

Когда вызывается polish(), графическое дерево сцены планирует событие полировки для данного элемента. Когда графическое дерево сцены готово отрисовать этот элемент, оно вызывает updatePolish(), чтобы выполнить необходимую компоновку элемента перед отрисовкой следующего кадра.

[virtual protected] void QQuickItem::wheelEvent(QWheelEvent *event)

Обработчик этого события может быть переопределен в подклассе для получения событий прокрутки для элемента. Информация о событии предоставляется параметром event.

Событие по умолчанию принимается, поэтому нет необходимости явно принимать событие при переопределении этой функции. Если вы не принимаете событие, вызовите event->ignore().

[protected] bool QQuickItem::widthValid() const

Возвращает, установлена ли явно свойство ширины.

QQuickWindow *QQuickItem::window() const

Возвращает окно, в котором отрисовывается этот элемент.

У элемента нет окна до тех пор, пока он не будет назначен в сцену. Сигнал windowChanged() предоставляет уведомление как при добавлении элемента в сцену, так и при его удалении из сцены.