Класс QRect

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

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

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

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

Связанные свободные функции

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

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

Прямоугольник обычно представляется как верхняя левая точка и размер. Размер (width и height) прямоугольника 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()

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

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

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

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

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

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

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

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

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

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

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

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.

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

См. также 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.

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

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

int QRect::left() const

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

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

QRect QRect::marginsAdded(const QMargins &margins) const

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

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

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

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().

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 относительно текущего положения.

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.

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

См. также 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&().

QRect &QRect::operator+=(const QMargins &margins)

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

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

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

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|().