QLabel: Allow pixmap() and picture() 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][QtWidgets][QLabel] QLabel::pixmap() and QLabel::picture()
can now return by-value instead of by-pointer.

Task-number: QTBUG-48701
Change-Id: I23ce319a7b1f757e1f4dec697551bb472e92fabf
Reviewed-by: André Hartmann <aha_1980@gmx.de>

src/corelib/global/qnamespace.h

@@ -1767,6 +1767,9 @@ public:
         PassThrough
     };
 
+    // QTBUG-48701
+    enum ReturnByValue_t { ReturnByValue }; // ### Qt 7: Remove me
+
 #ifndef Q_QDOC
     // NOTE: Generally, do not add QT_Q_ENUM if a corresponding Q_Q_FLAG exists.
     QT_Q_ENUM(ScrollBarPolicy)

src/corelib/global/qnamespace.qdoc

@@ -3319,3 +3319,13 @@
   \value RoundPreferFloor Round up for .75 and above.
   \value PassThrough Don't round.
 */
+
+/*!
+  \enum Qt::ReturnByValue_t
+  \since 5.15
+
+  This is a dummy type, designed to help users transition from certain deprecated APIs to their replacement APIs.
+
+  \sa QLabel::picture()
+  \sa QLabel::pixmap()
+*/

src/widgets/accessible/simplewidgets.cpp

@@ -76,6 +76,9 @@
 #include <qlineedit.h>
 #include <private/qlineedit_p.h>
 #endif
+#ifndef QT_NO_PICTURE
+#include <QtGui/qpicture.h>
+#endif
 #include <qstyle.h>
 #include <qstyleoption.h>
 #include <qtextdocument.h>
@@ -431,10 +434,10 @@ QAccessible::Role QAccessibleDisplay::role() const
 #if QT_CONFIG(label)
     QLabel *l = qobject_cast<QLabel*>(object());
     if (l) {
-        if (l->pixmap())
+        if (!l->pixmap(Qt::ReturnByValue).isNull())
             return QAccessible::Graphic;
 #ifndef QT_NO_PICTURE
-        if (l->picture())
+        if (!l->picture(Qt::ReturnByValue).isNull())
             return QAccessible::Graphic;
 #endif
 #if QT_CONFIG(movie)
@@ -558,10 +561,7 @@ QSize QAccessibleDisplay::imageSize() const
 #endif
         return QSize();
 #if QT_CONFIG(label)
-    const QPixmap *pixmap = label->pixmap();
-    if (!pixmap)
-        return QSize();
-    return pixmap->size();
+    return label->pixmap(Qt::ReturnByValue).size();
 #endif
 }
 
@@ -574,8 +574,7 @@ QPoint QAccessibleDisplay::imagePosition() const
 #endif
         return QPoint();
 #if QT_CONFIG(label)
-    const QPixmap *pixmap = label->pixmap();
-    if (!pixmap)
+    if (label->pixmap(Qt::ReturnByValue).isNull())
         return QPoint();
 
     return QPoint(label->mapToGlobal(label->pos()));

src/widgets/dialogs/qmessagebox.cpp

@@ -305,7 +305,7 @@ void QMessageBoxPrivate::setupLayout()
     Q_Q(QMessageBox);
     delete q->layout();
     QGridLayout *grid = new QGridLayout;
-    bool hasIcon = iconLabel->pixmap() && !iconLabel->pixmap()->isNull();
+    bool hasIcon = !iconLabel->pixmap(Qt::ReturnByValue).isNull();
 
     if (hasIcon)
         grid->addWidget(iconLabel, 0, 0, 2, 1, Qt::AlignTop);
@@ -1323,9 +1323,7 @@ void QMessageBox::setIcon(Icon icon)
 QPixmap QMessageBox::iconPixmap() const
 {
     Q_D(const QMessageBox);
-    if (d->iconLabel && d->iconLabel->pixmap())
-        return *d->iconLabel->pixmap();
-    return QPixmap();
+    return d->iconLabel->pixmap(Qt::ReturnByValue);
 }
 
 void QMessageBox::setIconPixmap(const QPixmap &pixmap)

src/widgets/dialogs/qwizard.cpp

@@ -452,8 +452,8 @@ public:
     }
 
     QSize minimumSizeHint() const override {
-        if (pixmap() && !pixmap()->isNull())
-            return pixmap()->size() / pixmap()->devicePixelRatio();
+        if (!pixmap(Qt::ReturnByValue).isNull())
+            return pixmap(Qt::ReturnByValue).size() / pixmap(Qt::ReturnByValue).devicePixelRatio();
         return QFrame::minimumSizeHint();
     }
 

src/widgets/widgets/qlabel.cpp

@@ -188,8 +188,13 @@ QLabelPrivate::~QLabelPrivate()
 */
 
 #ifndef QT_NO_PICTURE
+#if QT_DEPRECATED_SINCE(5, 15)
 /*!
-    Returns the label's picture or nullptr if the label doesn't have a
+    \deprecated
+
+    New code should use the other overload which returns QPicture by-value.
+
+    This function returns the label's picture or \c nullptr if the label doesn't have a
     picture.
 */
 
@@ -198,6 +203,37 @@ const QPicture *QLabel::picture() const
     Q_D(const QLabel);
     return d->picture;
 }
+#endif // QT_DEPRECATED_SINCE(5, 15)
+
+/*!
+    \since 5.15
+    Returns the label's picture.
+
+    Previously, Qt provided a version of \c picture() which returned the picture
+    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 QPicture *picPtr = label->picture();
+    QPicture picVal = label->picture(Qt::ReturnByValue);
+    \endcode
+
+    If you disable the deprecated version using the QT_DISABLE_DEPRECATED_BEFORE
+    macro, then you can omit \c Qt::ReturnByValue as shown below:
+
+    \code
+    QPicture picVal = label->picture();
+    \endcode
+*/
+
+QPicture QLabel::picture(Qt::ReturnByValue_t) const
+{
+    Q_D(const QLabel);
+    if (d->picture)
+        return *(d->picture);
+    return QPicture();
+}
 #endif
 
 
@@ -352,9 +388,27 @@ void QLabel::clear()
 
 /*!
     \property QLabel::pixmap
-    \brief the label's pixmap
+    \brief the label's pixmap.
 
-    If no pixmap has been set this will return nullptr.
+    Previously, Qt provided a version of \c pixmap() which returned the pixmap
+    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 QPixmap *pixmapPtr = label->pixmap();
+    QPixmap pixmapVal = label->pixmap(Qt::ReturnByValue);
+    \endcode
+
+    If you disable the deprecated version using the QT_DISABLE_DEPRECATED_BEFORE
+    macro, then you can omit \c Qt::ReturnByValue as shown below:
+
+    \code
+    QPixmap pixmapVal = label->pixmap();
+    \endcode
+
+    If no pixmap has been set, the deprecated getter function will return
+    \c nullptr.
 
     Setting the pixmap clears any previous content. The buddy
     shortcut, if any, is disabled.
@@ -373,11 +427,29 @@ void QLabel::setPixmap(const QPixmap &pixmap)
     d->updateLabel();
 }
 
+#if QT_DEPRECATED_SINCE(5, 15)
+/*!
+    \deprecated
+
+    New code should use the other overload which returns QPixmap by-value.
+*/
 const QPixmap *QLabel::pixmap() const
 {
     Q_D(const QLabel);
     return d->pixmap;
 }
+#endif // QT_DEPRECATED_SINCE(5, 15)
+
+/*!
+    \since 5.15
+*/
+QPixmap QLabel::pixmap(Qt::ReturnByValue_t) const
+{
+    Q_D(const QLabel);
+    if (d->pixmap)
+        return *(d->pixmap);
+    return QPixmap();
+}
 
 #ifndef QT_NO_PICTURE
 /*!

src/widgets/widgets/qlabel.h

@@ -72,9 +72,25 @@ public:
     ~QLabel();
 
     QString text() const;
-    const QPixmap *pixmap() const;
+
+#if QT_DEPRECATED_SINCE(5,15)
+    QT_DEPRECATED_VERSION_X(5, 15, "Use the other overload which returns QPixmap by-value")
+    const QPixmap *pixmap() const; // ### Qt 7: Remove function
+
+    QPixmap pixmap(Qt::ReturnByValue_t) const;
+#else
+    QPixmap pixmap(Qt::ReturnByValue_t = Qt::ReturnByValue) const; // ### Qt 7: Remove arg
+#endif // QT_DEPRECATED_SINCE(5,15)
+
 #ifndef QT_NO_PICTURE
-    const QPicture *picture() const;
+#  if QT_DEPRECATED_SINCE(5,15)
+    QT_DEPRECATED_VERSION_X(5, 15, "Use the other overload which returns QPicture by-value")
+    const QPicture *picture() const; // ### Qt 7: Remove function
+
+    QPicture picture(Qt::ReturnByValue_t) const;
+#  else
+    QPicture picture(Qt::ReturnByValue_t = Qt::ReturnByValue) const; // ### Qt 7: Remove arg
+#  endif // QT_DEPRECATED_SINCE(5,15)
 #endif
 #if QT_CONFIG(movie)
     QMovie *movie() const;