QCursor: Allow bitmap() and mask() to return by-value

The previous versions of these functions that returned by-pointer are
held over from Qt 1 times. They are inconsistent with the rest of the
Qt API.

[ChangeLog][QtGui][QCursor] QCursor::bitmap() and QCursor::mask()
can now return by-value instead of by-pointer.

Task-number: QTBUG-48701
Change-Id: I3ca4f0c28d5c831727a60309facfb49c74673bb7
Reviewed-by: Richard Moe Gustavsen <richard.gustavsen@qt.io>

src/gui/kernel/qcursor.cpp

@@ -325,7 +325,7 @@ QDataStream &operator<<(QDataStream &s, const QCursor &c)
         if (isPixmap)
             s << c.pixmap();
         else
-            s << *c.bitmap() << *c.mask();
+            s << c.bitmap(Qt::ReturnByValue) << c.mask(Qt::ReturnByValue);
         s << c.hotSpot();
     }
     return s;
@@ -565,7 +565,12 @@ void QCursor::setShape(Qt::CursorShape shape)
     }
 }
 
+#if QT_DEPRECATED_SINCE(5, 15)
 /*!
+    \deprecated
+
+    New code should use the other overload which returns QBitmap by-value.
+
     Returns the cursor bitmap, or \nullptr if it is one of the
     standard cursors.
 */
@@ -577,6 +582,10 @@ const QBitmap *QCursor::bitmap() const
 }
 
 /*!
+    \deprecated
+
+    New code should use the other overload which returns QBitmap by-value.
+
     Returns the cursor bitmap mask, or \nullptr if it is one of the
     standard cursors.
 */
@@ -587,6 +596,71 @@ const QBitmap *QCursor::mask() const
         QCursorData::initialize();
     return d->bmm;
 }
+#endif // QT_DEPRECATED_SINCE(5, 15)
+
+/*!
+    \since 5.15
+
+    Returns the cursor bitmap, or a null bitmap if it is one of the
+    standard cursors.
+
+    Previously, Qt provided a version of \c bitmap() which returned the bitmap
+    by-pointer. That version is now deprecated. To maintain compatibility
+    with old code, you can explicitly differentiate between the by-pointer
+    function and the by-value function:
+
+    \code
+    const QBitmap *bmpPtr = cursor->bitmap();
+    QBitmap bmpVal = cursor->bitmap(Qt::ReturnByValue);
+    \endcode
+
+    If you disable the deprecated version, then you can omit \c Qt::ReturnByValue
+    as shown below:
+
+    \code
+    QBitmap bmpVal = cursor->bitmap();
+    \endcode
+*/
+QBitmap QCursor::bitmap(Qt::ReturnByValue_t) const
+{
+    if (!QCursorData::initialized)
+        QCursorData::initialize();
+    if (d->bm)
+        return *(d->bm);
+    return QBitmap();
+}
+
+/*!
+    \since 5.15
+
+    Returns the cursor bitmap mask, or a null bitmap if it is one of the
+    standard cursors.
+
+    Previously, Qt provided a version of \c mask() which returned the bitmap
+    by-pointer. That version is now deprecated. To maintain compatibility
+    with old code, you can explicitly differentiate between the by-pointer
+    function and the by-value function:
+
+    \code
+    const QBitmap *bmpPtr = cursor->mask();
+    QBitmap bmpVal = cursor->mask(Qt::ReturnByValue);
+    \endcode
+
+    If you disable the deprecated version, then you can omit \c Qt::ReturnByValue
+    as shown below:
+
+    \code
+    QBitmap bmpVal = cursor->mask();
+    \endcode
+*/
+QBitmap QCursor::mask(Qt::ReturnByValue_t) const
+{
+    if (!QCursorData::initialized)
+        QCursorData::initialize();
+    if (d->bmm)
+        return *(d->bmm);
+    return QBitmap();
+}
 
 /*!
     Returns the cursor pixmap. This is only valid if the cursor is a

src/gui/kernel/qcursor.h

@@ -97,8 +97,19 @@ public:
     Qt::CursorShape shape() const;
     void setShape(Qt::CursorShape newShape);
 
-    const QBitmap *bitmap() const;
-    const QBitmap *mask() const;
+#if QT_DEPRECATED_SINCE(5, 15)
+    QT_DEPRECATED_VERSION_X(5, 15, "Use the other overload which returns QBitmap by-value")
+    const QBitmap *bitmap() const; // ### Qt 7: Remove function
+
+    QT_DEPRECATED_VERSION_X(5, 15, "Use the other overload which returns QBitmap by-value")
+    const QBitmap *mask() const; // ### Qt 7: Remove function
+
+    QBitmap bitmap(Qt::ReturnByValue_t) const;
+    QBitmap mask(Qt::ReturnByValue_t) const;
+#else
+    QBitmap bitmap(Qt::ReturnByValue_t = Qt::ReturnByValue) const; // ### Qt 7: Remove arg
+    QBitmap mask(Qt::ReturnByValue_t = Qt::ReturnByValue) const; // ### Qt 7: Remove arg
+#endif // QT_DEPRECATED_SINCE(5, 15)
     QPixmap pixmap() const;
     QPoint hotSpot() const;
 

src/plugins/platforms/windows/qwindowscursor.cpp

@@ -80,10 +80,10 @@ QWindowsPixmapCursorCacheKey::QWindowsPixmapCursorCacheKey(const QCursor &c)
     : bitmapCacheKey(c.pixmap().cacheKey()), maskCacheKey(0)
 {
     if (!bitmapCacheKey) {
-        Q_ASSERT(c.bitmap());
-        Q_ASSERT(c.mask());
-        bitmapCacheKey = c.bitmap()->cacheKey();
-        maskCacheKey = c.mask()->cacheKey();
+        Q_ASSERT(!c.bitmap(Qt::ReturnByValue).isNull());
+        Q_ASSERT(!c.mask(Qt::ReturnByValue).isNull());
+        bitmapCacheKey = c.bitmap(Qt::ReturnByValue).cacheKey();
+        maskCacheKey = c.mask(Qt::ReturnByValue).cacheKey();
     }
 }
 
@@ -169,9 +169,9 @@ static HCURSOR createBitmapCursor(const QImage &bbits, const QImage &mbits,
 // Create a cursor from image and mask of the format QImage::Format_Mono.
 static HCURSOR createBitmapCursor(const QCursor &cursor, qreal scaleFactor = 1)
 {
-    Q_ASSERT(cursor.shape() == Qt::BitmapCursor && cursor.bitmap());
-    QImage bbits = cursor.bitmap()->toImage();
-    QImage mbits = cursor.mask()->toImage();
+    Q_ASSERT(cursor.shape() == Qt::BitmapCursor && !cursor.bitmap(Qt::ReturnByValue).isNull());
+    QImage bbits = cursor.bitmap(Qt::ReturnByValue).toImage();
+    QImage mbits = cursor.mask(Qt::ReturnByValue).toImage();
     scaleFactor /= bbits.devicePixelRatioF();
     if (!qFuzzyCompare(scaleFactor, 1)) {
         const QSize scaledSize = (QSizeF(bbits.size()) * scaleFactor).toSize();