Revision control
++ // Copyright (C) 2024 The Qt Company Ltd.
++ // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
++ // Qt-Security score:significant reason:default
++
++ #include <QtQuick/private/qquicksafearea_p.h>
++
++ #include <QtQuick/private/qquickanchors_p_p.h>
++ #include <QtQuick/private/qquickitem_p.h>
++ #include <QtQuick/private/qquickflickable_p.h>
++ #include <QtQuick/qquickwindow.h>
++ #include <QtQuick/qquickitem.h>
++
++ QT_BEGIN_NAMESPACE
++
++ Q_STATIC_LOGGING_CATEGORY(lcSafeArea, "qt.quick.safearea", QtWarningMsg)
++
++ /*!
++ \qmltype SafeArea
++ \nativetype QQuickSafeArea
++ \inqmlmodule QtQuick
++ \ingroup qtquick-visual
++ \since 6.9
++ \brief Provides access to the safe area properties of the item or window.
++
++ The SafeArea attached type provides information about the areas of
++ an Item or Window where content may risk being overlapped by other
++ UI elements, such as system title bars or status bars.
++
++ This information can be used to lay out children of an item within
++ the safe area of the item, while still allowing a background color
++ or effect to span the entire item.
++
++ \table
++ \row
++ \li \snippet qml/safearea/basic.qml 0
++ \li \inlineimage safearea-ios.webp
++ {iPhone showing content respecting safe area margins}
++ \endtable
++
++ The SafeArea margins are relative to the item they attach to. If an
++ ancestor item has laid out its children within the safe area margins,
++ any descendant item with its own SafeArea attached will report zero
++ margins, unless \l{Additional margins}{additional margins} have been
++ added.
++
++ \note An item should not be positioned based on \e{its own} safe area,
++ as that would result in a binding loop.
++
++ \section2 Additional margins
++
++ Sometimes an item's layout involves child items that overlap each other,
++ for example in a window with a semi transparent header, where the rest
++ of the window content flows underneath the header.
++
++ In this scenario, the item may reflect the header's position and size
++ to the child items via the additionalMargins property.
++
++ The additional margins will be added to any margins that the
++ item already picks up from its parent hierarchy (including system
++ margins, such as title bars or status bars), and child items will
++ reflect the combined margins accordingly.
++
++ \table
++ \row
++ \li \snippet qml/safearea/additional.qml 0
++ \li \br \inlineimage safearea-ios-header.webp
++ {iPhone with header adding additional safe area margin}
++ \endtable
++
++ In the example above, the header item is positioned at the top of
++ the window, which may potentially overlap with existing safe area
++ margins coming from the window. To account for this we only add
++ additional margins for the part of the header that extends beyond
++ the window's safe area margins.
++
++ \note In this example the header item does not overlap the child item,
++ as the goal is to show how the items are positioned and resized in
++ response to safe area margin changes.
++
++ \section2 Controls
++
++ Applying safe area margins to a Control is straightforward,
++ as Control already offers properties to add padding to the
++ control's content item.
++
++ \snippet qml/safearea/controls.qml 0
++ */
++
++ QQuickSafeArea *QQuickSafeArea::qmlAttachedProperties(QObject *attachee)
++ {
++ auto *item = qobject_cast<QQuickItem*>(attachee);
++ if (!item) {
++ if (auto *window = qobject_cast<QQuickWindow*>(attachee))
++ item = window->contentItem();
++ }
++ if (!item) {
++ if (auto *safeAreaAttachable = qobject_cast<QQuickSafeAreaAttachable*>(attachee))
++ item = safeAreaAttachable->safeAreaAttachmentItem();
++ }
++ if (!item) {
++ qmlWarning(attachee) << "SafeArea can not be attached to this type";
++ return nullptr;
++ }
++
++ // We may already have created a safe area for Window, and are now
++ // requesting one for Window.contentItem (or the other way around).
++ // As both map to the same safe area item, we need to check first
++ // if we already have created one for this item.
++ if (auto *safeArea = item->findChild<QQuickSafeArea*>(Qt::FindDirectChildrenOnly))
++ return safeArea;
++
++ return new QQuickSafeArea(item);
++ }
++
++ QQuickSafeArea::QQuickSafeArea(QQuickItem *item)
++ : QObject(item)
++ {
++ qCInfo(lcSafeArea) << "Creating" << this;
++
++ connect(item, &QQuickItem::windowChanged,
++ this, &QQuickSafeArea::windowChanged);
++
++ item->setFlag(QQuickItem::ItemObservesViewport);
++ QQuickItemPrivate::get(item)->addItemChangeListener(
++ this, QQuickItemPrivate::Matrix);
++
++ updateSafeArea();
++ }
++
++ QQuickSafeArea::~QQuickSafeArea()
++ {
++ qCInfo(lcSafeArea) << "Destroying" << this;
++
++ const auto listenedItems = m_listenedItems;
++ for (const auto &item : listenedItems) {
++ if (!item)
++ continue;
++ auto *itemPrivate = QQuickItemPrivate::get(item);
++ itemPrivate->removeItemChangeListener(this,
++ QQuickItemPrivate::Matrix);
++ itemPrivate->removeItemChangeListener(this,
++ QQuickItemPrivate::Geometry);
++ }
++ }
++
++ /*!
++ \qmlpropertygroup QtQuick::SafeArea::margins
++ \qmlproperty real QtQuick::SafeArea::margins.top
++ \qmlproperty real QtQuick::SafeArea::margins.left
++ \qmlproperty real QtQuick::SafeArea::margins.right
++ \qmlproperty real QtQuick::SafeArea::margins.bottom
++ \readonly
++
++ This property holds the safe area margins, relative
++ to the attached item.
++
++ \sa additionalMargins
++ */
++ QMarginsF QQuickSafeArea::margins() const
++ {
++ return m_safeAreaMargins;
++ }
++
++ /*!
++ \qmlpropertygroup QtQuick::SafeArea::additionalMargins
++ \qmlproperty real QtQuick::SafeArea::additionalMargins.top
++ \qmlproperty real QtQuick::SafeArea::additionalMargins.left
++ \qmlproperty real QtQuick::SafeArea::additionalMargins.right
++ \qmlproperty real QtQuick::SafeArea::additionalMargins.bottom
++
++ This property holds the additional safe area margins for the item.
++
++ The additional safe area margins can not be negative, and will be
++ automatically clamped to 0.
++
++ The resulting safe area margins of the item are the sum of the inherited
++ margins (for example from title bars or status bar) and the additional
++ margins applied to the item.
++
++ \sa margins
++ */
++
++ void QQuickSafeArea::setAdditionalMargins(const QMarginsF &additionalMargins)
++ {
++ // Additional margins should never be negative
++ auto newMargins = additionalMargins | QMarginsF();
++
++ if (newMargins == m_additionalMargins)
++ return;
++
++ m_additionalMargins = newMargins;
++
++ emit additionalMarginsChanged();
++
++ auto *attachedItem = qobject_cast<QQuickItem*>(parent());
++ updateSafeAreasRecursively(attachedItem);
++ }
++
++ QMarginsF QQuickSafeArea::additionalMargins() const
++ {
++ return m_additionalMargins;
++ }
++
++ /*
++ Maps the safe area \a margins from \a fromItem to \a toItem
++ */
++ static QMarginsF toLocalMargins(const QMarginsF &margins, QQuickItem *fromItem, QQuickItem *toItem)
++ {
++ if (margins.isNull())
++ return margins;
++
++ const auto localMarginRect = fromItem->mapRectToItem(toItem,
++ QRectF(margins.left(), margins.top(),
++ fromItem->width() - margins.left() - margins.right(),
++ fromItem->height() - margins.top() - margins.bottom()));
++
++ // Only return a mapped margin if there was an original margin
++ return QMarginsF(
++ margins.left() > 0 ? localMarginRect.left() : 0,
++ margins.top() > 0 ? localMarginRect.top() : 0,
++ margins.right() > 0 ? toItem->width() - localMarginRect.right() : 0,
++ margins.bottom() > 0 ? toItem->height() - localMarginRect.bottom() : 0
++ ) | QMarginsF();
++ }
++
++ void QQuickSafeArea::updateSafeArea()
++ {
++ qCDebug(lcSafeArea) << "✨ Updating" << this;
++
++ auto *attachedItem = qobject_cast<QQuickItem*>(parent());
++ if (!QQuickItemPrivate::get(attachedItem)->componentComplete) {
++ qCDebug(lcSafeArea) << attachedItem << "is not complete. Deferring";
++ return;
++ }
++
++ QMarginsF inheritedMargins;
++ auto *parentItem = attachedItem->parentItem();
++ while (parentItem) {
++ if (qobject_cast<QQuickFlickable*>(parentItem)) {
++ // Stop propagation of safe areas when we hit a Flickable,
++ // as items within the content item that account for safe
++ // area margins will continuously update when the content
++ // item is moved, which is not necessarily what the user
++ // expects.
++ qCDebug(lcSafeArea) << "Stopping safe area margin propagation on" << parentItem;
++ break;
++ }
++
++
++ // We attach the safe area to the relevant item for an attachee
++ // such as QQuickWindow or QQuickPopup, so we can't go via
++ // qmlAttachedPropertiesObject to find the safe area for an
++ // item, as the attached object cache is based on the original
++ // attachee.
++ if (auto *safeArea = parentItem->findChild<QQuickSafeArea*>(Qt::FindDirectChildrenOnly)) {
++ inheritedMargins = safeArea->margins();
++ break;
++ }
++
++ parentItem = parentItem->parentItem();
++ }
++
++ const auto *window = attachedItem->window();
++ if (!parentItem && window) {
++ // We didn't find a parent item with a safe area,
++ // so inherit the margins from the window.
++ parentItem = window->contentItem();
++ inheritedMargins = window->safeAreaMargins();
++ }
++
++ auto inheritedMarginsMapped = toLocalMargins(inheritedMargins, parentItem, attachedItem);
++
++ // Make sure margins are never negative
++ const QMarginsF newMargins = QMarginsF() | (inheritedMarginsMapped + additionalMargins());
++
++ if (newMargins != m_safeAreaMargins) {
++ qCDebug(lcSafeArea) << "Margins changed from" << m_safeAreaMargins
++ << "to" << newMargins
++ << "based on inherited" << inheritedMargins
++ << "mapped to local" << inheritedMarginsMapped
++ << "and additional" << additionalMargins();
++
++ m_safeAreaMargins = newMargins;
++
++ if (emittingMarginsUpdate) {
++ // We are already in the process of emitting an update for this
++ // safe area, which resulted in the safe area margins changing.
++ // This can be a binding loop if the margins do not stabilize,
++ // which we'll detect when we return from the root emit below.
++ qCDebug(lcSafeArea) << "Already emitting update for" << this;
++ return;
++ }
++
++ QScopedValueRollback blocker(emittingMarginsUpdate, true);
++ emit marginsChanged();
++
++ if (m_safeAreaMargins != newMargins) {
++ qCDebug(lcSafeArea) << "⚠️ Possible binding loop for" << this
++ << newMargins << "changed to" << m_safeAreaMargins;
++
++ QScopedValueRollback blocker(detectedPossibleBindingLoop, true);
++
++ for (int i = 0; i < 5; ++i) {
++ auto marginsBeforeEmit = m_safeAreaMargins;
++ emit marginsChanged();
++ if (m_safeAreaMargins == marginsBeforeEmit) {
++ qCDebug(lcSafeArea) << "✅ Margins stabilized for" << this;
++ return;
++ }
++
++ qCDebug(lcSafeArea) << qPrintable(QStringLiteral("‼️").repeated(i + 1))
++ << marginsBeforeEmit << "changed to" << m_safeAreaMargins;
++ }
++
++ qmlWarning(attachedItem) << "Safe area binding loop detected";
++ }
++ }
++ }
++
++ void QQuickSafeArea::windowChanged()
++ {
++ updateSafeArea();
++ }
++
++ void QQuickSafeArea::itemTransformChanged(QQuickItem *item, QQuickItem *transformedItem)
++ {
++ Q_ASSERT(item == parent());
++
++ auto *transformedItemPrivate = QQuickItemPrivate::get(transformedItem);
++ qCDebug(lcSafeArea) << "📏 Transform changed for" << transformedItem
++ << "with dirty state" << transformedItemPrivate->dirtyToString();
++
++ if (qobject_cast<QQuickFlickable*>(transformedItem->parentItem())) {
++ qCDebug(lcSafeArea) << "Ignoring transform change for Flickable content item";
++ return;
++ }
++
++ // The order of transform and geometry change callbacks may not be in paint order,
++ // so to ensure we update the safe areas in paint order we find the item closest
++ // to the transformed item with a safe area, and let that safe area trigger the
++ // update recursively in paint order.
++ if (transformedItem != item) {
++ for (auto *parent = item->parentItem(); parent; parent = parent->parentItem()) {
++ if (parent->findChild<QQuickSafeArea*>(Qt::FindDirectChildrenOnly))
++ item = parent;
++
++ if (parent == transformedItem)
++ break;
++ }
++ }
++
++ if (item != parent()) {
++ qCDebug(lcSafeArea) << "Found" << item << "closer to transformed item than" << this;
++ return;
++ }
++
++ // The dirtying of position and size will be followed by a geometry change,
++ // which via anchors or event listeners may result in an ancestor invalidating
++ // its transform, which might invalidate the margins we're about to compute.
++ // Instead of processing the margin change now, possibly resulting in a flip-
++ // flop of the margins, we wait for the geometry notification, where the item
++ // hierarchy has already reacted to the geometry change of the transformed item.
++ // This accounts for anchors, and items that listen to geometry changes, but not
++ // property bindings, as those are emitted after notifying listeners (us) about
++ // the geometry change.
++ auto dirtyAttributes = transformedItemPrivate->dirtyAttributes;
++ if (dirtyAttributes & (QQuickItemPrivate::Position | QQuickItemPrivate::Size)) {
++ qCDebug(lcSafeArea) << "Deferring update of" << this << "until geometry change";
++ transformedItemPrivate->addItemChangeListener(
++ this, QQuickItemPrivate::Geometry);
++ return;
++ }
++
++ updateSafeAreasRecursively(item);
++ }
++
++ void QQuickSafeArea::itemGeometryChanged(QQuickItem *item, QQuickGeometryChange change, const QRectF &oldGeometry)
++ {
++ Q_UNUSED(change);
++ Q_UNUSED(oldGeometry);
++
++ auto *itemPrivate = QQuickItemPrivate::get(item);
++ itemPrivate->removeItemChangeListener(this, QQuickItemPrivate::Geometry);
++
++ qCDebug(lcSafeArea) << "📐 Geometry changed for" << item << "from" << oldGeometry
++ << "to" << QRectF(item->position(), item->size());
++
++ updateSafeAreasRecursively(item);
++ }
++
++ void QQuickSafeArea::updateSafeAreasRecursively(QQuickItem *item)
++ {
++ Q_ASSERT(item);
++
++ if (auto *safeArea = item->findChild<QQuickSafeArea*>(Qt::FindDirectChildrenOnly))
++ safeArea->updateSafeArea();
++
++ auto *itemPrivate = QQuickItemPrivate::get(item);
++ const auto paintOrderChildItems = itemPrivate->paintOrderChildItems();
++ for (auto *child : paintOrderChildItems)
++ updateSafeAreasRecursively(child);
++ }
++
++ void QQuickSafeArea::addSourceItem(QQuickItem *item)
++ {
++ m_listenedItems << item;
++ }
++
++ void QQuickSafeArea::removeSourceItem(QQuickItem *item)
++ {
++ m_listenedItems.removeAll(item);
++ }
++
++ #ifndef QT_NO_DEBUG_STREAM
++ QDebug operator<<(QDebug debug, const QQuickSafeArea *safeArea)
++ {
++ QDebugStateSaver saver(debug);
++ debug.nospace();
++
++ if (!safeArea) {
++ debug << "QQuickSafeArea(nullptr)";
++ return debug;
++ }
++
++ debug << safeArea->metaObject()->className() << '(' << static_cast<const void *>(safeArea);
++
++ debug << ", attachedItem=" << safeArea->parent();
++ debug << ", safeAreaMargins=" << safeArea->m_safeAreaMargins;
++ debug << ", additionalMargins=" << safeArea->additionalMargins();
++
++ debug << ')';
++ return debug;
++ }
++ #endif // QT_NO_DEBUG_STREAM
++
++ QQuickSafeAreaAttachable::~QQuickSafeAreaAttachable() = default;
++
++ QT_END_NAMESPACE
++
++ #include "moc_qquicksafearea_p.cpp"