diff options
Diffstat (limited to 'src/quick/items/qquickitem.cpp')
| -rw-r--r-- | src/quick/items/qquickitem.cpp | 111 |
1 files changed, 86 insertions, 25 deletions
diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp index 497672b497..33da9762d3 100644 --- a/src/quick/items/qquickitem.cpp +++ b/src/quick/items/qquickitem.cpp @@ -905,7 +905,7 @@ bool QQuickKeysAttached::isConnected(const char *signalName) const */ /*! - \qmlproperty list<Object> QtQuick::Keys::forwardTo + \qmlproperty list<Item> QtQuick::Keys::forwardTo This property provides a way to forward key presses, key releases, and keyboard input coming from input methods to other items. This can be useful when you want @@ -2095,7 +2095,7 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus) /*! \class QQuickItem::ItemChangeData \inmodule QtQuick - \brief Adds supplimentary information to the QQuickItem::itemChange() + \brief Adds supplementary information to the QQuickItem::itemChange() function. The meaning of each member of this class is defined by the change type. @@ -2125,25 +2125,31 @@ void QQuickItemPrivate::updateSubFocusItem(QQuickItem *scope, bool focus) /*! \variable QQuickItem::ItemChangeData::realValue - Contains supplimentary information to the QQuickItem::itemChange() function. + The numeric value that has changed: \l {QQuickItem::opacity()}{opacity}, + \l {QQuickItem::rotation()}{rotation} or + \l {QScreen::devicePixelRatio}{device pixel ratio}. \sa QQuickItem::ItemChange */ /*! \variable QQuickItem::ItemChangeData::boolValue - Contains supplimentary information to the QQuickItem::itemChange() function. + The boolean value that has changed: \l {QQuickItem::visible()}{visible}, + \l {QQuickItem::enabled()}{enabled}, \l {QQuickItem::activeFocus()}{activeFocus} + or \l {QQuickItem::antialiasing()}{antialiasing}. \sa QQuickItem::ItemChange */ /*! \variable QQuickItem::ItemChangeData::item - Contains supplimentary information to the QQuickItem::itemChange() function. + The item that has been added or removed as a \l{QQuickItem::childItems()}{child}, + or the new \l{QQuickItem::parentItem()}{parent}. \sa QQuickItem::ItemChange */ /*! \variable QQuickItem::ItemChangeData::window - Contains supplimentary information to the QQuickItem::itemChange() function. + The \l{QQuickWindow}{window} in which the item has been shown, or \c nullptr + if the item has been removed from a window. \sa QQuickItem::ItemChange */ @@ -3711,6 +3717,9 @@ QList<QQuickItem *> QQuickItem::childItems() const If clipping is enabled, an item will clip its own painting, as well as the painting of its children, to its bounding rectangle. + + \note Clipping can affect rendering performance. See \l {Clipping} for more + information. */ /*! \property QQuickItem::clip @@ -4534,10 +4543,10 @@ static bool unwrapMapFromToFromItemArgs(QQmlV4Function *args, const QQuickItem * } /*! - \qmlmethod object QtQuick::Item::mapFromItem(Item item, real x, real y) - \qmlmethod object QtQuick::Item::mapFromItem(Item item, point p) - \qmlmethod object QtQuick::Item::mapFromItem(Item item, real x, real y, real width, real height) - \qmlmethod object QtQuick::Item::mapFromItem(Item item, rect r) + \qmlmethod point QtQuick::Item::mapFromItem(Item item, real x, real y) + \qmlmethod point QtQuick::Item::mapFromItem(Item item, point p) + \qmlmethod rect QtQuick::Item::mapFromItem(Item item, real x, real y, real width, real height) + \qmlmethod rect QtQuick::Item::mapFromItem(Item item, rect r) Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in \a item's coordinate system, to this item's coordinate system, and returns a \l point or \l rect @@ -4589,10 +4598,10 @@ QTransform QQuickItem::itemTransform(QQuickItem *other, bool *ok) const } /*! - \qmlmethod object QtQuick::Item::mapToItem(Item item, real x, real y) - \qmlmethod object QtQuick::Item::mapToItem(Item item, point p) - \qmlmethod object QtQuick::Item::mapToItem(Item item, real x, real y, real width, real height) - \qmlmethod object QtQuick::Item::mapToItem(Item item, rect r) + \qmlmethod point QtQuick::Item::mapToItem(Item item, real x, real y) + \qmlmethod point QtQuick::Item::mapToItem(Item item, point p) + \qmlmethod rect QtQuick::Item::mapToItem(Item item, real x, real y, real width, real height) + \qmlmethod rect QtQuick::Item::mapToItem(Item item, rect r) Maps the point (\a x, \a y) or rect (\a x, \a y, \a width, \a height), which is in this item's coordinate system, to \a item's coordinate system, and returns a \l point or \l rect @@ -4674,7 +4683,7 @@ static bool unwrapMapFromToFromGlobalArgs(QQmlV4Function *args, const QQuickItem /*! \since 5.7 - \qmlmethod object QtQuick::Item::mapFromGlobal(real x, real y) + \qmlmethod point QtQuick::Item::mapFromGlobal(real x, real y) Maps the point (\a x, \a y), which is in the global coordinate system, to the item's coordinate system, and returns a \l point matching the mapped coordinate. @@ -4701,7 +4710,7 @@ void QQuickItem::mapFromGlobal(QQmlV4Function *args) const /*! \since 5.7 - \qmlmethod object QtQuick::Item::mapToGlobal(real x, real y) + \qmlmethod point QtQuick::Item::mapToGlobal(real x, real y) Maps the point (\a x, \a y), which is in this item's coordinate system, to the global coordinate system, and returns a \l point matching the mapped coordinate. @@ -4784,14 +4793,24 @@ void QQuickItem::forceActiveFocus() void QQuickItem::forceActiveFocus(Qt::FocusReason reason) { + Q_D(QQuickItem); setFocus(true, reason); QQuickItem *parent = parentItem(); + QQuickItem *scope = nullptr; while (parent) { if (parent->flags() & QQuickItem::ItemIsFocusScope) { parent->setFocus(true, reason); + if (!scope) + scope = parent; } parent = parent->parentItem(); } + // In certain reparenting scenarios, d->focus might be true and the scope + // might also have focus, so that setFocus() returns early without actually + // acquiring active focus, because it thinks it already has it. In that + // case, try to set the DeliveryAgent's active focus. (QTBUG-89736). + if (scope && !d->activeFocus && d->window) + QQuickWindowPrivate::get(d->window)->setFocusInScope(scope, this, Qt::OtherFocusReason); } /*! @@ -7852,22 +7871,64 @@ bool QQuickItem::contains(const QPointF &point) const \qmlproperty QObject* QtQuick::Item::containmentMask \since 5.11 This property holds an optional mask for the Item to be used in the - QtQuick::Item::contains method. - QtQuick::Item::contains main use is currently to determine whether - an input event has landed into the item or not. + QtQuick::Item::contains() method. Its main use is currently to determine + whether a \l {QPointerEvent}{pointer event} has landed into the item or not. By default the \l contains method will return true for any point - within the Item's bounding box. \c containmentMask allows for a - more fine-grained control. For example, the developer could - define and use an AnotherItem element as containmentMask, - which has a specialized contains method, like: + within the Item's bounding box. \c containmentMask allows for + more fine-grained control. For example, if a custom C++ + QQuickItem subclass with a specialized contains() method + is used as containmentMask: \code Item { id: item; containmentMask: AnotherItem { id: anotherItem } } \endcode - \e{item}'s contains method would then return true only if - \e{anotherItem}'s contains implementation returns true. + \e{item}'s contains method would then return \c true only if + \e{anotherItem}'s contains() implementation returns \c true. + + A \l Shape can be used as a mask, to make an item react to + \l {QPointerEvent}{pointer events} only within a non-rectangular region: + + \table + \row + \li \image containmentMask-shape.gif + \li \snippet qml/item/containmentMask-shape.qml 0 + \endtable + + It is also possible to define the contains method in QML. For example, + to create a circular item that only responds to events within its + actual bounds: + + \table + \row + \li \image containmentMask-circle.gif + \li \snippet qml/item/containmentMask-circle-js.qml 0 + \endtable + + \sa {Qt Quick Examples - Shapes} +*/ +/*! + \property QQuickItem::containmentMask + \since 5.11 + This property holds an optional mask to be used in the contains() method, + which is mainly used for hit-testing each \l QPointerEvent. + + By default, \l contains() will return \c true for any point + within the Item's bounding box. But any QQuickItem, or any QObject + that implements a function of the form + \code + Q_INVOKABLE bool contains(const QPointF &point) const; + \endcode + can be used as a mask, to defer hit-testing to that object. + + \note contains() is called frequently during event delivery. + Deferring hit-testing to another object slows it down somewhat. + containmentMask() can cause performance problems if that object's + contains() method is not efficient. If you implement a custom + QQuickItem subclass, you can alternatively override contains(). + + \sa contains() */ QObject *QQuickItem::containmentMask() const { |