API Cleanup: Remove focusReason from QQuickItem's public API and add docs

Make changes according to API review comments:

- Remove focusReason property and relevant API from QQuickItem. Move
it to private API in QQuickItemPrivate and rename it to
lastFocusChangeReason. Defer exposing this property to
QML for now. (In Qt7 we can expose it by adding it as a signal
parameter to QQuickItem's focusChanged signal)

- Add documentation for focusPolicy C++ API

- Don't mark focusPolicy property as FINAL

Partially reverts 1ca9928856c47108000ffe5f310f2b99740f087b

Task-number: QTBUG-119952
Task-number: QTBUG-117596
Pick-to: 6.7
Change-Id: Ib4632b86c64e3221ca5e651d80d58b8c89fcf2b7
Reviewed-by: Mitch Curtis <mitch.curtis@qt.io>

3 files changed, 34 insertions, 36 deletions

diff --git a/src/quick/items/qquickitem.cpp b/src/quick/items/qquickitem.cpp
index 8a92841176..58fb51e98a 100644
--- a/src/quick/items/qquickitem.cpp
+++ b/src/quick/items/qquickitem.cpp
@@ -1739,6 +1739,19 @@ bool QQuickItemPrivate::setFocusIfNeeded(QEvent::Type eventType)
     return false;
 }
 
+Qt::FocusReason QQuickItemPrivate::lastFocusChangeReason() const
+{
+    return static_cast<Qt::FocusReason>(focusReason);
+}
+
+void QQuickItemPrivate::setLastFocusChangeReason(Qt::FocusReason reason)
+{
+    if (focusReason == reason)
+        return;
+
+    focusReason = reason;
+}
+
 /*!
     \class QQuickItem
     \brief The QQuickItem class provides the most basic of all visual items in \l {Qt Quick}.
@@ -4098,6 +4111,7 @@ void QQuickItem::inputMethodEvent(QInputMethodEvent *event)
   */
 void QQuickItem::focusInEvent(QFocusEvent *event)
 {
+    Q_D(QQuickItem);
 #if QT_CONFIG(accessibility)
     if (QAccessible::isActive()) {
         if (QObject *acc = QQuickAccessibleAttached::findAccessible(this)) {
@@ -4106,7 +4120,7 @@ void QQuickItem::focusInEvent(QFocusEvent *event)
         }
     }
 #endif
-    setFocusReason(event->reason());
+    d->setLastFocusChangeReason(event->reason());
 }
 
 /*!
@@ -4118,7 +4132,8 @@ void QQuickItem::focusInEvent(QFocusEvent *event)
   */
 void QQuickItem::focusOutEvent(QFocusEvent *event)
 {
-    setFocusReason(event->reason());
+    Q_D(QQuickItem);
+    d->setLastFocusChangeReason(event->reason());
 }
 
 /*!
@@ -7916,31 +7931,6 @@ QQuickItem *QQuickItem::scopedFocusItem() const
 }
 
 /*!
-    \qmlproperty enumeration QtQuick::Item::focusReason
-    \readonly
-    \since 6.7
-
-    \input item.qdocinc focus-reason
-
-    \note This property was a member of {QQuickControl} {Control} until Qt 6.7.
-*/
-Qt::FocusReason QQuickItem::focusReason() const
-{
-    Q_D(const QQuickItem);
-    return static_cast<Qt::FocusReason>(d->focusReason);
-}
-
-void QQuickItem::setFocusReason(Qt::FocusReason reason)
-{
-    Q_D(QQuickItem);
-    if (d->focusReason == reason)
-        return;
-
-    d->focusReason = reason;
-    emit focusReasonChanged();
-}
-
-/*!
     \qmlproperty enumeration QtQuick::Item::focusPolicy
     \since 6.7
 
@@ -7952,7 +7942,15 @@ void QQuickItem::setFocusReason(Qt::FocusReason reason)
     \value Qt.WheelFocus  The item accepts focus by tabbing, clicking, and using the mouse wheel.
     \value Qt.NoFocus     The item does not accept focus.
 
-    \note This property was a member of {QQuickControl} {Control} until Qt 6.7.
+    \note This property was a member of \l {QQuickControl} {Control} until Qt 6.7.
+*/
+/*!
+    \property QQuickItem::focusPolicy
+    \since 6.7
+
+    This property determines the way the item accepts focus.
+
+    \note This property was a member of \l {QQuickControl} {Control} until Qt 6.7.
 */
 Qt::FocusPolicy QQuickItem::focusPolicy() const
 {
@@ -7963,6 +7961,11 @@ Qt::FocusPolicy QQuickItem::focusPolicy() const
     return static_cast<Qt::FocusPolicy>(policy);
 }
 
+/*!
+    Sets the focus policy of this item to \a policy.
+
+    \sa focusPolicy()
+*/
 void QQuickItem::setFocusPolicy(Qt::FocusPolicy policy)
 {
     Q_D(QQuickItem);
diff --git a/src/quick/items/qquickitem.h b/src/quick/items/qquickitem.h
index f7f34f6c44..cfef2ea040 100644
--- a/src/quick/items/qquickitem.h
+++ b/src/quick/items/qquickitem.h
@@ -102,10 +102,7 @@ class Q_QUICK_EXPORT QQuickItem : public QObject, public QQmlParserStatus
     Q_PROPERTY(bool activeFocus READ hasActiveFocus NOTIFY activeFocusChanged FINAL)
     Q_PROPERTY(bool activeFocusOnTab READ activeFocusOnTab WRITE setActiveFocusOnTab NOTIFY activeFocusOnTabChanged FINAL REVISION(2, 1))
 
-    QT6_ONLY(Q_PROPERTY(Qt::FocusPolicy focusPolicy READ focusPolicy WRITE setFocusPolicy NOTIFY focusPolicyChanged))
-    QT7_ONLY(Q_PROPERTY(Qt::FocusPolicy focusPolicy READ focusPolicy WRITE setFocusPolicy NOTIFY focusPolicyChanged FINAL))
-    QT6_ONLY(Q_PROPERTY(Qt::FocusReason focusReason READ focusReason WRITE setFocusReason NOTIFY focusReasonChanged))
-    QT7_ONLY(Q_PROPERTY(Qt::FocusReason focusReason READ focusReason NOTIFY focusReasonChanged FINAL))
+    Q_PROPERTY(Qt::FocusPolicy focusPolicy READ focusPolicy WRITE setFocusPolicy NOTIFY focusPolicyChanged)
 
     Q_PROPERTY(qreal rotation READ rotation WRITE setRotation NOTIFY rotationChanged)
     Q_PROPERTY(qreal scale READ scale WRITE setScale NOTIFY scaleChanged)
@@ -278,9 +275,6 @@ public:
     Qt::FocusPolicy focusPolicy() const;
     void setFocusPolicy(Qt::FocusPolicy policy);
 
-    Qt::FocusReason focusReason() const;
-    void setFocusReason(Qt::FocusReason reason);
-
     bool isAncestorOf(const QQuickItem *child) const;
 
     Qt::MouseButtons acceptedMouseButtons() const;
@@ -394,7 +388,6 @@ Q_SIGNALS:
     void stateChanged(const QString &);
     void focusChanged(bool);
     void activeFocusChanged(bool);
-    Q_REVISION(6, 7) void focusReasonChanged();
     Q_REVISION(6, 7) void focusPolicyChanged();
     Q_REVISION(2, 1) void activeFocusOnTabChanged(bool);
     void parentChanged(QQuickItem *);
diff --git a/src/quick/items/qquickitem_p.h b/src/quick/items/qquickitem_p.h
index 8bcbd69232..58800ab88d 100644
--- a/src/quick/items/qquickitem_p.h
+++ b/src/quick/items/qquickitem_p.h
@@ -561,6 +561,8 @@ public:
     void updateSubFocusItem(QQuickItem *scope, bool focus);
 
     bool setFocusIfNeeded(QEvent::Type);
+    Qt::FocusReason lastFocusChangeReason() const;
+    void setLastFocusChangeReason(Qt::FocusReason reason);
 
     QTransform windowToItemTransform() const;
     QTransform itemToWindowTransform() const;