Класс QRect

Класс QRect определяет прямоугольник на плоскости с использованием целочисленной точности. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются реентерабельными.

Открытые функции

Статические публичные члены

Связанные нечлены

Подробное описание

Прямоугольник обычно выражается как верхний левый угол и размер. Размер (ширина и высота) QRect всегда соответствует математическому прямоугольнику, который образует основу для его отрисовки.

QRect можно создать с помощью набора целых чисел левого, верхнего, ширины и высоты или из QPoint и QSize. Следующий код создаёт два идентичных прямоугольника.

QRect r1(100, 200, 11, 16);
QRect r2(QPoint(100, 200), QSize(11, 16));

Существует третий конструктор, создающий QRect с использованием координат верхнего левого и нижнего правого углов, но мы рекомендуем избегать его использования. Объяснение заключается в том, что по историческим причинам значения, возвращаемые функциями bottom() и right(), отклоняются от истинного нижнего правого угла прямоугольника.

Класс QRect предоставляет набор функций, возвращающих различные координаты прямоугольника и позволяющих манипулировать ими. QRect также предоставляет функции для перемещения прямоугольника относительно различных координат. Кроме того, есть функция moveTo(), которая перемещает прямоугольник, оставляя его верхний левый угол в заданных координатах. В качестве альтернативы, функция translate() перемещает прямоугольник на заданный смещение относительно текущего положения, а функция translated() возвращает перемещённую копию этого прямоугольника.

Функция size() возвращает размеры прямоугольника как QSize. Размеры также можно получить отдельно с помощью функций width() и height(). Для изменения размеров используйте функции setSize(), setWidth() или setHeight(). В качестве альтернативы, размеры можно изменить, применив любую из функций, устанавливающих координаты прямоугольника, например, setBottom() или setRight().

Функция contains() указывает, находится ли заданная точка внутри прямоугольника или нет, а функция intersects() возвращает true если этот прямоугольник пересекается с заданным прямоугольником. Класс QRect также предоставляет функцию intersected(), которая возвращает пересекающийся прямоугольник, и функцию united(), которая возвращает прямоугольник, охватывающий данный прямоугольник и этот:

intersected()	united()

Функция isEmpty() возвращает true если left() > right() или top() > bottom(). Обратите внимание, что пустой прямоугольник не является допустимым: функция isValid() возвращает true если left() <= right() и top() <= bottom(). С другой стороны, нулевой прямоугольник (isNull() == true) имеет ширину и высоту, равные 0.

Обратите внимание, что из-за того, как определены QRect и QRectF, пустой QRect определяется по существу так же, как и QRectF.

Наконец, объекты QRect можно потоковать и сравнивать.

Отрисовка

При использовании отрисовщика с антиалиасингом граничная линия QRect будет отрисовываться симметрично по обе стороны от граничной линии математического прямоугольника. Но при использовании отрисовщика без алиасинга (по умолчанию) применяются другие правила.

Затем, при отрисовке с пером шириной один пиксел граничная линия QRect будет отрисована справа и снизу от граничной линии математического прямоугольника.

При отрисовке с пером шириной два пикселя граничная линия будет разделена посередине математическим прямоугольником. Это будет происходить всякий раз, когда перо имеет чётное количество пикселей, в то время как отрисовка с пером с нечётным количеством пикселей будет отрисовывать лишний пиксель справа и снизу от математического прямоугольника, как в случае с пером шириной один пиксель.

Логическое представление	Перо шириной один пиксель
Перо шириной два пикселя	Перо шириной три пикселя

Координаты

Класс QRect предоставляет набор функций, возвращающих различные координаты прямоугольника и позволяющих манипулировать ими. QRect также предоставляет функции для перемещения прямоугольника относительно различных координат.

Например, функции left(), setLeft() и moveLeft() в качестве примера: left() возвращает координату x левой грани прямоугольника, setLeft() устанавливает левую грань прямоугольника в заданную координату x (может изменить ширину, но никогда не изменит правую грань прямоугольника), а moveLeft() перемещает весь прямоугольник горизонтально, оставляя левую грань прямоугольника в заданной координате x и сохраняя его размер неизменным.

Обратите внимание, что по историческим причинам значения, возвращаемые функциями bottom() и right(), отклоняются от истинного нижнего правого угла прямоугольника: функция right() возвращает left() + width() - 1, а функция bottom() возвращает top() + height() - 1. То же самое относится к точке, возвращаемой удобной функцией bottomRight(). Кроме того, координаты x и y функций topRight() и bottomLeft() соответственно содержат ту же разницу от истинных правой и нижней граней.

Мы рекомендуем использовать x() + width() и y() + height() для нахождения истинного нижнего правого угла и избегать использования right() и bottom(). Другим решением является использование QRectF: Класс QRectF определяет прямоугольник в плоскости с использованием плавающей точки для координат, и функции QRectF::right() и QRectF::bottom() возвращают координаты справа и снизу.

Также можно добавлять смещения к координатам этого прямоугольника с помощью функции adjust(), а также получать новый прямоугольник на основе корректировок исходного прямоугольника с помощью функции adjusted(). Если ширина или высота отрицательны, используйте функцию normalized() для получения прямоугольника, где углы поменяны местами.

Кроме того, QRect предоставляет функцию getCoords() для извлечения координат левого верхнего и правого нижнего углов прямоугольника, а также функцию getRect() для извлечения левого верхнего угла, ширины и высоты прямоугольника. Используйте функцию setCoords() и setRect() для одновременного изменения координат и размеров прямоугольника.

Ограничения

QRect ограничен минимальными и максимальными значениями для типа int. Операции над QRect, которые могут привести к значениям за пределами этого диапазона, приведут к неопределенному поведению.

См. также QRectF и QRegion.

Документация по функциям-членам

QRect::QRect(int x, int y, int width, int height)

Создаёт прямоугольник с левым верхним углом (x, y) и заданной width и height.

См. также setRect().

QRect::QRect(const QPoint &topLeft, const QSize &size)

Создаёт прямоугольник с заданным левым верхним углом topLeft и заданным размером size.

См. также setTopLeft() и setSize().

QRect::QRect(const QPoint &topLeft, const QPoint &bottomRight)

Создаёт прямоугольник с заданными левым верхним углом topLeft и правым нижним углом bottomRight, оба включены.

Если bottomRight находится выше и левее topLeft, то прямоугольник строится без включения углов.

Примечание: Для того, чтобы оба угла были включены независимо от относительного порядка, используйте span().

См. также setTopLeft(), setBottomRight() и span().

QRect::QRect()

Создаёт нулевой прямоугольник.

См. также isNull().

void QRect::adjust(int dx1, int dy1, int dx2, int dy2)

Добавляет dx1, dy1, dx2 и dy2 соответственно к существующим координатам прямоугольника.

См. также adjusted() и setRect().

QRect QRect::adjusted(int dx1, int dy1, int dx2, int dy2) const

Возвращает новый прямоугольник, к которому добавлены dx1, dy1, dx2 и dy2 соответственно к существующим координатам текущего прямоугольника.

См. также adjust().

int QRect::bottom() const

Возвращает y-координату нижней границы прямоугольника.

Обратите внимание, что по историческим причинам эта функция возвращает top() + height() - 1; используйте y() + height() для получения истинной y-координаты.

См. также setBottom(), bottomLeft() и bottomRight().

QPoint QRect::bottomLeft() const

Возвращает координаты левого нижнего угла прямоугольника. Обратите внимание, что по историческим причинам эта функция возвращает QPoint(left(), top() + height() - 1).

См. также setBottomLeft(), bottom() и left().

QPoint QRect::bottomRight() const

Возвращает координаты правого нижнего угла прямоугольника.

Обратите внимание, что по историческим причинам эта функция возвращает QPoint(left() + width() -1, top() + height() - 1).

См. также setBottomRight(), bottom() и right().

QPoint QRect::center() const

Возвращает центральную точку прямоугольника.

См. также moveCenter().

bool QRect::contains(const QPoint &point, bool proper = false) const

Возвращает true , если заданная точка point находится внутри или на границе прямоугольника, в противном случае возвращает false. Если proper равно true, эта функция возвращает true только если заданная точка point находится внутри прямоугольника (т.е. не на границе).

См. также intersects().

bool QRect::contains(const QRect &rectangle, bool proper = false) const

Это перегруженная функция.

Возвращает true , если заданный прямоугольник rectangle находится внутри этого прямоугольника. В противном случае возвращает false. Если proper равно true, эта функция возвращает true только если прямоугольник rectangle полностью находится внутри этого прямоугольника (не на границе).

bool QRect::contains(int x, int y) const

Это перегруженная функция.

Возвращает true , если точка (x, y) находится внутри этого прямоугольника, в противном случае возвращает false.

bool QRect::contains(int x, int y, bool proper) const

Это перегруженная функция.

Возвращает true , если точка (x, y) находится внутри или на границе прямоугольника, в противном случае возвращает false. Если proper равно true, эта функция возвращает true только если точка полностью находится внутри прямоугольника (не на границе).

void QRect::getCoords(int *x1, int *y1, int *x2, int *y2) const

Извлекает координаты левого верхнего угла прямоугольника в *x1 и *y1, а координаты правого нижнего угла в *x2 и *y2.

См. также setCoords() и getRect().

void QRect::getRect(int *x, int *y, int *width, int *height) const

Извлекает координаты левого верхнего угла прямоугольника в *x и *y, а его размеры в *width и *height.

См. также setRect() и getCoords().

int QRect::height() const

Возвращает высоту прямоугольника.

См. также setHeight(), width() и size().

QRect QRect::intersected(const QRect &rectangle) const

Возвращает пересечение этого прямоугольника и заданного rectangle. Обратите внимание, что r.intersected(s) эквивалентно r & s.

См. также intersects(), united() и operator&=().

bool QRect::intersects(const QRect &rectangle) const

Возвращает true , если этот прямоугольник пересекается с заданным прямоугольником rectangle (т.е., существует хотя бы один пиксель, который находится в обоих прямоугольниках), в противном случае возвращает false.

Прямоугольник пересечения можно получить с помощью функции intersected().

См. также contains().

bool QRect::isEmpty() const

Возвращает true , если прямоугольник пустой, в противном случае возвращает false.

Пустой прямоугольник имеет left() > right() или top() > bottom(). Пустой прямоугольник не является допустимым (т.е., isEmpty() == !isValid()).

Используйте функцию normalized() для получения прямоугольника, где углы поменяны местами.

См. также isNull(), isValid() и normalized().

bool QRect::isNull() const

Возвращает true , если прямоугольник нулевой, в противном случае возвращает false.

Нулевой прямоугольник имеет ширину и высоту, равные 0 (т.е., right() == left() - 1 и bottom() == top() - 1). Нулевой прямоугольник также является пустым и, следовательно, не допустимым.

См. также isEmpty() и isValid().

bool QRect::isValid() const

Возвращает true , если прямоугольник допустимый, в противном случае возвращает false.

Действительный прямоугольник имеет левую() границу <= правую() границу и верхнюю() границу <= нижнюю() границу. Обратите внимание, что для недействительных прямоугольников не определены такие нетривиальные операции, как пересечение. Действительный прямоугольник не пустой (т.е., isValid() == !isEmpty()).

См. также isNull(), isEmpty() и normalized().

int QRect::left() const

Возвращает координату x левой границы прямоугольника. Эквивалентно x().

См. также setLeft(), topLeft() и bottomLeft().

[since 5.1] QRect QRect::marginsAdded(const QMargins &margins) const

Возвращает прямоугольник, расширенный на заданные margins.

Эта функция была добавлена в Qt 5.1.

См. также operator+=(), marginsRemoved() и operator-=().

[since 5.1] QRect QRect::marginsRemoved(const QMargins &margins) const

Удаляет заданные margins из прямоугольника, сужая его.

Эта функция была добавлена в Qt 5.1.

См. также marginsAdded(), operator+=() и operator-=().

void QRect::moveBottom(int y)

Перемещает прямоугольник вертикально, оставляя нижнюю границу прямоугольника в заданной координате y. Размер прямоугольника не меняется.

См. также bottom(), setBottom() и moveTop().

void QRect::moveBottomLeft(const QPoint &position)

Перемещает прямоугольник, оставляя нижнюю левую точку в заданной точке position. Размер прямоугольника не меняется.

См. также setBottomLeft(), moveBottom() и moveLeft().

void QRect::moveBottomRight(const QPoint &position)

Перемещает прямоугольник, оставляя нижнюю правую точку в заданной точке position. Размер прямоугольника не меняется.

См. также setBottomRight(), moveRight() и moveBottom().

void QRect::moveCenter(const QPoint &position)

Перемещает прямоугольник, оставляя центральную точку в заданной точке position. Размер прямоугольника не меняется.

См. также center().

void QRect::moveLeft(int x)

Перемещает прямоугольник горизонтально, оставляя левую границу прямоугольника в заданной координате x. Размер прямоугольника не меняется.

См. также left(), setLeft() и moveRight().

void QRect::moveRight(int x)

Перемещает прямоугольник горизонтально, оставляя правую границу прямоугольника в заданной координате x. Размер прямоугольника не меняется.

См. также right(), setRight() и moveLeft().

void QRect::moveTo(int x, int y)

Перемещает прямоугольник, оставляя верхнюю левую точку в заданной позиции (x, y). Размер прямоугольника не меняется.

См. также translate() и moveTopLeft().

void QRect::moveTo(const QPoint &position)

Перемещает прямоугольник, оставляя верхнюю левую точку в заданной position.

void QRect::moveTop(int y)

Перемещает прямоугольник вертикально, оставляя верхнюю границу прямоугольника в заданной координате y. Размер прямоугольника не меняется.

См. также top(), setTop() и moveBottom().

void QRect::moveTopLeft(const QPoint &position)

Перемещает прямоугольник, оставляя верхнюю левую точку в заданной position. Размер прямоугольника не меняется.

См. также setTopLeft(), moveTop() и moveLeft().

void QRect::moveTopRight(const QPoint &position)

Перемещает прямоугольник, оставляя верхнюю правую точку в заданной position. Размер прямоугольника не меняется.

См. также setTopRight(), moveTop() и moveRight().

QRect QRect::normalized() const

Возвращает нормализованный прямоугольник; т.е., прямоугольник с неотрицательной шириной и высотой.

Если width() < 0, функция меняет местами левую и правую точки, а если height() < 0, она меняет местами верхнюю и нижнюю точки. Точки при этом изменяются с неинклюзивных на инклюзивные.

См. также isValid() и isEmpty().

int QRect::right() const

Возвращает координату x правой границы прямоугольника.

Обратите внимание, что по историческим причинам эта функция возвращает left() + width() - 1; используйте x() + width() для получения истинной координаты x.

См. также setRight(), topRight() и bottomRight().

void QRect::setBottom(int y)

Устанавливает нижнюю границу прямоугольника в заданную координату y. Может изменить высоту, но никогда не изменит верхнюю границу прямоугольника.

См. также bottom() и moveBottom().

void QRect::setBottomLeft(const QPoint &position)

Устанавливает нижнюю левую точку прямоугольника в заданную точку position. Может изменить размер, но никогда не изменит верхнюю правую точку прямоугольника.

См. также bottomLeft() и moveBottomLeft().

void QRect::setBottomRight(const QPoint &position)

Устанавливает нижнюю правую точку прямоугольника в заданную точку position. Может изменить размер, но никогда не изменит верхнюю левую точку прямоугольника.

См. также bottomRight() и moveBottomRight().

void QRect::setCoords(int x1, int y1, int x2, int y2)

Устанавливает координаты верхней левой точки прямоугольника в (x1, y1), и координаты его нижней правой точки в (x2, y2).

См. также getCoords() и setRect().

void QRect::setHeight(int height)

Устанавливает высоту прямоугольника в заданную height. Изменяется нижняя граница, но не верхняя.

См. также height() и setSize().

void QRect::setLeft(int x)

Устанавливает левую границу прямоугольника в заданную координату x. Может изменить ширину, но никогда не изменит правую границу прямоугольника.

Эквивалентно setX().

См. также left() и moveLeft().

void QRect::setRect(int x, int y, int width, int height)

Устанавливает координаты верхней левой точки прямоугольника в (x, y), а его размер — в заданную width и height.

См. также getRect() и setCoords().

void QRect::setRight(int x)

Устанавливает правую границу прямоугольника в заданную координату x. Может изменить ширину, но никогда не изменит левую границу прямоугольника.

См. также right() и moveRight().

void QRect::setSize(const QSize &size)

Устанавливает размер прямоугольника в заданный size. Верхняя левая точка не перемещается.

См. также size(), setWidth() и setHeight().

void QRect::setTop(int y)

Устанавливает верхнюю границу прямоугольника в заданную координату y. Может изменить высоту, но никогда не изменит нижнюю границу прямоугольника.

Эквивалентно setY().

См. также top() и moveTop().

void QRect::setTopLeft(const QPoint &position)

Устанавливает верхний левый угол прямоугольника в заданную точку position. Может изменить размер, но никогда не изменит нижний правый угол прямоугольника.

См. также topLeft() и moveTopLeft().

void QRect::setTopRight(const QPoint &position)

Устанавливает верхний правый угол прямоугольника в заданную точку position. Может изменить размер, но никогда не изменит нижний левый угол прямоугольника.

См. также topRight() и moveTopRight().

void QRect::setWidth(int width)

Устанавливает ширину прямоугольника в заданную width. Правая граница меняется, но не левая.

См. также width() и setSize().

void QRect::setX(int x)

Устанавливает левую границу прямоугольника в заданную координату x. Может изменить ширину, но никогда не изменит правую границу прямоугольника.

Эквивалентно setLeft().

См. также x(), setY() и setTopLeft().

void QRect::setY(int y)

Устанавливает верхнюю границу прямоугольника в заданную координату y. Может изменить высоту, но никогда не изменит нижнюю границу прямоугольника.

Эквивалентно setTop().

См. также y(), setX() и setTopLeft().

QSize QRect::size() const

Возвращает размер прямоугольника.

См. также setSize(), width() и height().

[static, since 6.0] QRect QRect::span(const QPoint &p1, const QPoint &p2)

Возвращает прямоугольник, охватывающий две точки p1 и p2, включая обе и всё между ними.

Эта функция была добавлена в Qt 6.0.

[since 5.8] CGRect QRect::toCGRect() const

Создаёт CGRect из QRect.

Эта функция была добавлена в Qt 5.8.

См. также QRectF::fromCGRect().

int QRect::top() const

Возвращает координату y верхней границы прямоугольника. Эквивалентно y().

См. также setTop(), topLeft() и topRight().

QPoint QRect::topLeft() const

Возвращает координаты верхнего левого угла прямоугольника.

См. также setTopLeft(), top() и left().

QPoint QRect::topRight() const

Возвращает координаты верхнего правого угла прямоугольника.

Обратите внимание, что по историческим причинам эта функция возвращает QPoint(left() + width() -1, top()).

См. также setTopRight(), top() и right().

void QRect::translate(int dx, int dy)

Перемещает прямоугольник на dx по оси x и dy по оси y относительно текущего положения. Положительные значения перемещают прямоугольник вправо и вниз.

См. также moveTopLeft(), moveTo() и translated().

void QRect::translate(const QPoint &offset)

Это перегруженная функция.

Перемещает прямоугольник на offset.x() по оси x и offset.y() по оси y относительно текущего положения.

QRect QRect::translated(int dx, int dy) const

Возвращает копию прямоугольника, перемещённого на dx по оси x и dy по оси y относительно текущего положения. Положительные значения перемещают прямоугольник вправо и вниз.

См. также translate().

QRect QRect::translated(const QPoint &offset) const

Это перегруженная функция.

Возвращает копию прямоугольника, перемещённого на offset.x() по оси x и offset.y() по оси y относительно текущего положения.

[since 5.7] QRect QRect::transposed() const

Возвращает копию прямоугольника, в которой ширина и высота поменялись местами:

QRect r = {15, 51, 42, 24};
r = r.transposed(); // r == {15, 51, 24, 42}

Эта функция была добавлена в Qt 5.7.

См. также QSize::transposed().

QRect QRect::united(const QRect &rectangle) const

Возвращает ограничивающий прямоугольник для этого прямоугольника и заданного rectangle.

См. также intersected().

int QRect::width() const

Возвращает ширину прямоугольника.

См. также setWidth(), height() и size().

int QRect::x() const

Возвращает координату x левой границы прямоугольника. Эквивалентно left().

См. также setX(), y() и topLeft().

int QRect::y() const

Возвращает координату y верхней границы прямоугольника. Эквивалентно top().

См. также setY(), x() и topLeft().

QRect QRect::operator&(const QRect &rectangle) const

Возвращает пересечение этого прямоугольника и заданного rectangle. Возвращает пустой прямоугольник, если пересечения нет.

См. также operator&=() и intersected().

QRect &QRect::operator&=(const QRect &rectangle)

Пересекает этот прямоугольник с заданным rectangle.

См. также intersected() и operator&().

[since 5.1] QRect &QRect::operator+=(const QMargins &margins)

Добавляет margins к прямоугольнику, расширяя его.

Эта функция была добавлена в Qt 5.1.

См. также marginsAdded(), marginsRemoved() и operator-=().

[since 5.1] QRect &QRect::operator-=(const QMargins &margins)

Возвращает прямоугольник, уменьшенный на margins.

Эта функция была добавлена в Qt 5.1.

См. также marginsRemoved(), operator+=() и marginsAdded().

QRect QRect::operator|(const QRect &rectangle) const

Возвращает ограничивающий прямоугольник для этого прямоугольника и заданного rectangle.

См. также operator|=() и united().

QRect &QRect::operator|=(const QRect &rectangle)

Объединяет этот прямоугольник с заданным rectangle.

См. также united() и operator|().