Класс QQuickItem

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

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

Открытые типы

Свойства

• 1 свойство унаследовано от QObject

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

• 31 public functions inherited from QObject
• 2 public functions inherited from QQmlParserStatus

Публичные слоты

• 1 public slot inherited from QObject

Сигналы

• 2 signals inherited from QObject

Статические публичные члены

• 9 static public members inherited from QObject

Защищенные функции

Реализованные защищённые функции

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

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

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

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

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

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

Все визуальные элементы QML рендерятся с использованием графика сцены, по умолчанию — высокопроизводительная низкоуровневая структура рендеринга, тесно связанная с OpenGL. Подклассы QQuickItem могут добавлять собственное содержимое в график сцены, установив флаг QQuickItem::ItemHasContents и переопределив функцию QQuickItem::updatePaintNode().

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

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

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

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

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

• График сцены становится недействительным; Это может произойти, например, если окно скрыто с помощью QQuickWindow::hide(). Если класс элемента реализует slot с именем invalidateSceneGraph(), этот слот будет вызван в потоке рендеринга, в то время как поток GUI заблокирован. Это эквивалентно подключению к QQuickWindow::sceneGraphInvalidated(). Контекст 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() для очистки графических ресурсов не рекомендуется, так как это произойдёт в произвольное время, и нет гарантии, что будет связан контекст OpenGL к моменту удаления.

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

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

Предупреждение: Использование QQuickPaintedItem использует непрямую 2D-поверхность для отрисовки контента, либо с помощью программной растризации, либо с использованием объекта буфера кадра OpenGL (FBO), поэтому отрисовка — это операция из двух шагов. Сначала растрируется поверхность, а затем рисуется поверхность. Использование 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().

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
        }
    }
}

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

Определяет естественную ширину или высоту элемента, если не указаны width или height.

По умолчанию неявный размер для большинства элементов равен 0x0, однако некоторые элементы имеют неявный размер, который нельзя переопределить, например, Image и Text.

Установка неявного размера полезна для определения компонентов, имеющих предпочтительный размер на основе их содержимого, например:

// 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
    }
}

Примечание: Использование implicitWidth элементов Text или TextEdit и явное задание ширины приводит к снижению производительности, так как текст необходимо разложить дважды.

QQuickItem::QQuickItem(QQuickItem *parent = nullptr)

Создаёт QQuickItem с заданным parent.

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

[override virtual] QQuickItem::~QQuickItem()

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

bool QQuickItem::acceptHoverEvents() const

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

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

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

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

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 в противном случае.

См. также 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)

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

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

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

См. также Перетаскивание и Перетаскивание и перемещение.

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

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

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

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

См. также Перетаскивание и Перетаскивание и перемещение.

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

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

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

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

См. также Перетаскивание и Перетаскивание и перемещение.

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

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

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

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

См. также Перетаскивание и Перетаскивание и перемещение.

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

Переопределённый метод из QObject::event().

bool QQuickItem::filtersChildMouseEvents() const

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

См. также 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.

void QQuickItem::forceActiveFocus(Qt::FocusReason reason)

Это перегруженная функция.

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

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

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

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

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

[virtual protected] void QQuickItem::geometryChanged(const QRectF &newGeometry, const QRectF &oldGeometry)

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

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

void QQuickItem::grabMouse()

Захватывает ввод мыши.

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

Предупреждение: эту функцию следует использовать с осторожностью.

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

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

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

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

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

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

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

void QQuickItem::grabTouchPoints(const QVector<int> &ids)

Захватывает точки касания, указанные в ids.

Эти точки касания будут принадлежать элементу до тех пор, пока не будут освобождены. В качестве альтернативы, захват может быть похищен элементом фильтрации, таким как Flickable. Используйте setKeepTouchGrab(), чтобы предотвратить похищение захвата.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если 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.

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.

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

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

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

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

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

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

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

[virtual protected] void QQuickItem::mouseUngrabEvent()

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

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

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

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

void QQuickItem::polish()

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

Когда граф сцены обработает запрос, он вызовет updatePolish() для этого элемента.

[virtual protected] void QQuickItem::releaseResources()

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

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

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

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

QQuickItem *QQuickItem::scopedFocusItem() const

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

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

void QQuickItem::setAcceptHoverEvents(bool enabled)

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

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

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

void QQuickItem::setSize(const QSizeF &size)

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

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

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

QSizeF QQuickItem::size() const

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

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

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

void QQuickItem::stackAfter(const QQuickItem *sibling)

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

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

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

Указанный sibling должен быть дочерним элементом этого элемента; то есть, они должны иметь того же непосредственного parent.

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

Освобождает захват мыши после вызова grabMouse().

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

void QQuickItem::ungrabTouchPoints()

Освобождает захват точек касания, принадлежащих этому элементу.

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

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

void QQuickItem::unsetCursor()

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

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

[slot] void QQuickItem::update()

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

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

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

[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() или добавление и удаление узлов, то реализация может решить не перерисовывать сцену снова, поскольку визуальный результат идентичен.

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

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

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

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

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

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