Класс 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
        }
    }
}

Item {
    x: 50
    y: 100

    // prints: QRectF(-10, -20, 30, 40)
    Component.onCompleted: print(childrenRect)

    Item {
        x: -10
        y: -20
        width: 30
        height: 40
    }
}

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::update() разрешается только для элементов, для которых задан QQuickItem::ItemHasContents.

[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() и acceptTouchEvents().

[invokable] 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 invokable] 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 *)

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

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

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

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

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

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

[invokable] void QQuickItem::forceActiveFocus()

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

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

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

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

См. также activeFocus.

[invokable, 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.

Примечание: Эта функция будет рендерить элемент на внеэкранной поверхности и копировать эту поверхность из памяти GPU в память CPU, что может быть достаточно дорогостоящим. Для «живого» предварительного просмотра используйте слои или 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, scale, rotation, transformOrigin и transform.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также Концепции - Визуальные координаты в 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()

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

[invokable] 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.

Примечание: В Qt 5 вызов setAcceptedMouseButtons() неявно заставлял элемент получать как события мыши, так и события касания; однако, рекомендовалось вызывать setAcceptTouchEvents() для подписки на них. В Qt 6 необходимо вызывать setAcceptTouchEvents() для продолжения получения этих событий.

См. также 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 предоставляет указатель на связанный с этим QQuickItem объект QSGTransformNode.

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() предоставляет уведомление как при вводе элемента в сцену, так и при удалении его из сцены.