From 48230dc882cb59c40e38bc6b8ccad3823cb2c0b6 Mon Sep 17 00:00:00 2001 From: Marc Mutz Date: Wed, 29 Nov 2017 20:06:30 +0100 Subject: QRegion: deprecate rects() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It was superseded by begin()/end() in Qt 5.8. The eventual removal of rects() will allow greater flexibility in the implementation's choice of data structure (std::vector, e.g., or QVarLengthArray). Remove all traces of rects() from the documentation. This means we need to copy information previously contained in the rects() docs to functions which previously just referred to rects(), in particular the begin()/end() familiy of functions. Change-Id: I90809809783252f7c552f24b4841f1e965580284 Reviewed-by: Mårten Nordheim Reviewed-by: Lars Knoll --- src/gui/painting/qregion.cpp | 51 ++++++++++++++++++++++++++++++-------------- src/gui/painting/qregion.h | 3 +++ 2 files changed, 38 insertions(+), 16 deletions(-) diff --git a/src/gui/painting/qregion.cpp b/src/gui/painting/qregion.cpp index dcff6a1d72..40cffe7cc6 100644 --- a/src/gui/painting/qregion.cpp +++ b/src/gui/painting/qregion.cpp @@ -81,8 +81,9 @@ QT_BEGIN_NAMESPACE contains() a QPoint or QRect. The bounding rectangle can be found with boundingRect(). - Iteration over the region (with begin(), end()) gives a decomposition of - the region into rectangles. The same sequence of rectangles is returned by rects(). + Iteration over the region (with begin(), end(), or C++11 + ranged-for loops) gives a decomposition of the region into + rectangles. Example of using complex regions: \snippet code/src_gui_painting_qregion.cpp 0 @@ -755,7 +756,8 @@ QRegion QRegion::intersect(const QRect &r) const \fn int QRegion::rectCount() const \since 4.6 - Returns the number of rectangles that will be returned in rects(). + Returns the number of rectangles that this region is composed of. + Same as \c{end() - begin()}. */ /*! @@ -917,20 +919,28 @@ QRegion QRegion::intersect(const QRect &r) const gives a rectangle that is QRect::isNull(). */ +#if QT_DEPRECATED_SINCE(5, 11) /*! \fn QVector QRegion::rects() const + \obsolete + + Use begin() and end() instead. Returns an array of non-overlapping rectangles that make up the region. The union of all the rectangles is equal to the original region. */ +#endif /*! \typedef QRegion::const_iterator \since 5.8 - An iterator over the QRects that make up the region. + An iterator over the non-overlapping rectangles that make up the + region. + + The union of all the rectangles is equal to the original region. QRegion does not offer mutable iterators. @@ -941,7 +951,10 @@ QRegion QRegion::intersect(const QRect &r) const \typedef QRegion::const_reverse_iterator \since 5.8 - A reverse iterator over the QRects that make up the region. + A reverse iterator over the non-overlapping rectangles that make up the + region. + + The union of all the rectangles is equal to the original region. QRegion does not offer mutable iterators. @@ -953,8 +966,9 @@ QRegion QRegion::intersect(const QRect &r) const \since 5.8 Returns a const_iterator pointing to the beginning of the range of - rectangles that make up this range, in the order in which rects() - returns them. + non-overlapping rectangles that make up the region. + + The union of all the rectangles is equal to the original region. \sa rbegin(), cbegin(), end() */ @@ -970,9 +984,10 @@ QRegion QRegion::intersect(const QRect &r) const \fn QRegion::end() const \since 5.8 - Returns a const_iterator pointing to one past the end of the range of - rectangles that make up this range, in the order in which rects() - returns them. + Returns a const_iterator pointing to one past the end of + non-overlapping rectangles that make up the region. + + The union of all the rectangles is equal to the original region. \sa rend(), cend(), begin() */ @@ -988,9 +1003,10 @@ QRegion QRegion::intersect(const QRect &r) const \fn QRegion::rbegin() const \since 5.8 - Returns a const_reverse_iterator pointing to the beginning of the range of - rectangles that make up this range, in the reverse order in which rects() - returns them. + Returns a const_reverse_iterator pointing to the beginning of the + range of non-overlapping rectangles that make up the region. + + The union of all the rectangles is equal to the original region. \sa begin(), crbegin(), rend() */ @@ -1006,9 +1022,10 @@ QRegion QRegion::intersect(const QRect &r) const \fn QRegion::rend() const \since 5.8 - Returns a const_reverse_iterator pointing to one past the end of the range of - rectangles that make up this range, in the reverse order in which rects() - returns them. + Returns a const_reverse_iterator pointing to one past the end of + the range of non-overlapping rectangles that make up the region. + + The union of all the rectangles is equal to the original region. \sa end(), crend(), rbegin() */ @@ -4348,6 +4365,7 @@ bool qt_region_strictContains(const QRegion ®ion, const QRect &rect) && rect.top() >= r1.top() && rect.bottom() <= r1.bottom()); } +#if QT_DEPRECATED_SINCE(5, 11) QVector QRegion::rects() const { if (d->qt_rgn) { @@ -4359,6 +4377,7 @@ QVector QRegion::rects() const return QVector(); } } +#endif QRegion::const_iterator QRegion::begin() const Q_DECL_NOTHROW { diff --git a/src/gui/painting/qregion.h b/src/gui/painting/qregion.h index 8dd7649447..9fe6ed5675 100644 --- a/src/gui/painting/qregion.h +++ b/src/gui/painting/qregion.h @@ -122,7 +122,10 @@ public: bool intersects(const QRect &r) const; QRect boundingRect() const Q_DECL_NOTHROW; +#if QT_DEPRECATED_SINCE(5, 11) + QT_DEPRECATED_X("Use begin()/end() instead") QVector rects() const; +#endif void setRects(const QRect *rect, int num); int rectCount() const Q_DECL_NOTHROW; #ifdef Q_COMPILER_MANGLES_RETURN_TYPE -- cgit v1.2.3