[Development] Updating holdover API from Qt 1 times

[Sze Howe Koh]

 QLabel returns some CoW types by-pointer as a legacy from Qt 1 times [1]:

    QPixmap *QLabel::pixmap() const;
    QPixture *QLabel::pixmap() const;

If you know of any other such API, please point them out!


Anyway, a few different ways have been proposed to modernize this API
[2][3][4], summarized below:

1) Add a non-overloaded version and deprecate the existing version:

    class QLabel {
        QPixmap *pixmap() const; // deprecated
        QPixmap labelPixmap() const; // new
    };


2) Keep the existing name but change the return type, with support for a
transition period:

    namespace Qt {
        struct ReturnByValue_t {};
        static Q_CONSTEXPR ReturnByValue_t ReturnByValue;
    }

    class QLabel {
        QPixmap *pixmap() const; // deprecated
        QPixmap pixmap(Qt::ReturnByValue_t) const; // new
    };

class QLabel {
#ifndef QT_NO_COW_POINTERS
    QPixmap *pixmap() const;
#endif
    QPixmap pixmap(Qt::ReturnByValue_t
#ifdef QT_NO_COW_POINTERS
            = ReturnByValue
#endif
    ) const;
}

// Without QT_NO_COW_POINTERS
QPixmap *pm1 = label->pixmap();
QPixmap pm2 = label->pixmap(Qt::ReturnByValue);

// With QT_NO_COW_POINTERS
QPixmap pm3 = label->pixmap();


3) Pick one of the options above, but go one step further and use
std::optional (C++17) instead of returning null objects. I imagine this
should apply more broadly to the whole of Qt, not just the functions
discussed here.


There's also Option (4): Leave it all alone; if it ain't broke don't fix it.


Which should we implement? I personally prefer (2) as it it can be added to
Qt 5.x and provides backward compatibility while keeping the nice compact
function names. We could enable QT_NO_COW by default in Qt 6.5 LTS and then
remove the old function and Qt::ReturnByValue_t in Qt 7.0.

I'm not sure I like the verbosity or SiC-ness of std::optional, hence I'm
asking for thoughts here.


Regards,
Sze-Howe

[1]
https://lists.qt-project.org/pipermail/development/2014-December/019376.html
[2]
https://lists.qt-project.org/pipermail/development/2014-December/019377.html
[3] https://codereview.qt-project.org/c/qt/qtbase/+/101233
[4] https://codereview.qt-project.org/c/qt/qtbase/+/267825
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.qt-project.org/pipermail/development/attachments/20190817/76d8105a/attachment.html>