QRect

La classe QRect définit un rectangle dans le plan utilisant une précision entière. Plus d'informations...

#include <QRect>

Voir la position dans l'arbre des classes.

Description détaillée

La classe QRect définit un rectangle dans le plan utilisant une précision entière.

Un rectangle est normalement défini par son coin supérieur gauche et sa taille. La taille (hauteur et largeur) d'un QRect est toujours équivalente au rectangle mathématique qui sert de base pour son rendu.

Un QRect peut-être construit avec un ensemble d'entiers désignant l'abscisse, l'ordonnée, la largeur et la hauteur ou bien avec un QPoint et un QSize. Le code suivant crée deux rectangles identiques.

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

Il y a un troisième constructeur qui crée un QRect grâce aux coordonnées des coins supérieur gauche et inférieur droit mais nous vous recommandons d'éviter de l'utiliser. En effet, pour des raisons historiques, les valeurs retournées par les fonctions bottom() et right() diffèrent du vrai coin inférieur droit du rectangle.

La classe QRect propose une collection de fonctions qui retournent les différentes coordonnées du rectangle et permettent la manipulation de celles-ci. QRect propose également des fonctions pour déplacer le rectangle par rapport à ces différentes coordonnées. En outre, il existe une fonction moveTo() qui déplace le rectangle, de façon à ce que son coin supérieur gauche ait les coordonnées données. D'autre part, la fonction translate() déplace le rectangle suivant le décalage donné par rapport à sa position actuelle et la fonction translated() retourne une copie translatée de ce rectangle.

La fonction size() retourne les dimensions du rectangle dans un QSize. Les dimensions peuvent également être récupérées séparément en utilisant les fonctions width() et height(). Pour manipuler les dimensions, utilisez les fonctions setSize(), setWidth() ou setHeight(). D'autre part, la taille peut être modifiée en utilisant l'une des fonctions permettant de changer les coordonnées du rectangle, comme par exemple setBottom() ou setRight().

La fonction contains() indique si le point donné est à l'intérieur du rectangle ou pas. La fonction intersects() retourne true si le rectangle intersecte un rectangle donné. La classe QRect possède également la fonction intersected() qui retourne le rectangle d'intersection et la fonction united() qui retourne le rectangle qui englobe ce rectangle et celui passé en argument :

intersected()	united()

La fonction isEmpty retourne true si left() > right() ou top() > bottom(). Notez qu'un rectangle vide n'est pas valide : la fonction isValid() retourne true si left() <= right() et top() <= bottom(). Un rectangle Null (isNull() == true), d'autre part, a une largeur et une hauteur nulles.

Notez que, de par la définition des classes QRect et QRectF, un QRect vide est défini essentiellement de la même façon qu'un QRectF.

Finalement, les objets QRect peuvent être mis sous la forme de flux et comparés.

Rendu

Quand vous utilisez un peintre avec anti-crénelage, le contour d'un QRect sera dessiné symétriquement des deux côtés du contour du rectangle mathématique. Cependant, quand vous utilisez un peintre avec crénelage (par défaut), le dessin ne s'effectue pas de la même manière.

Dans ce cas, quand vous utilisez un pinceau d'un pixel de largeur, le contour du QRect sera dessiné à droite et en dessous du contour du rectangle mathématique.

Quand vous utilisez un pinceau de deux pixels de largeur, le contour sera divisé en son milieu par le rectangle mathématique. Ce sera le cas à chaque fois que la largeur du pinceau aura un nombre pair de pixel. Quand le nombre de pixels du pinceau est impair, en revanche, le pixel supplémentaire sera dessiné à droite et en dessous du rectangle mathématique comme dans le cas d'un pinceau d'un pixel.

Représentation logique (rectangle mathématique)	Pinceau d'un pixel de large
Pinceau de deux pixels de large	Pinceau de trois pixels de large

Coordonnées

La classe QRect propose une collection de fonctions qui retournent les différentes coordonnées du rectangle et permet la manipulation de celles-ci. QRect propose également des fonctions pour déplacer le rectangle par rapport à ces différentes coordonnées.

Prenons pour exemple les fonctions left(), setLeft() et moveLeft() : left() retourne l'abscisse de l'arête gauche du rectangle, setLeft() définit l'abscisse de l'arête gauche du rectangle à l'abscisse x donnée (ce qui peut changer la largeur mais jamais l'arête droite du rectangle) et moveLeft() déplace horizontalement le rectangle entier, de façon à ce que son arête gauche ait l'abscisse x donnée et que sa taille reste inchangée.

Notez que, pour des raisons historiques, les valeurs retournées par les fonctions bottom() et right() diffèrent du vrai coin inférieur droit du rectangle : la fonction right() retourne left() + width() - 1 et la fonction bottom() top() + height() - 1. Il en va de même pour le point retourné par la fonction bottomRight(). En outre, l'abscisse et l'ordonnée des fonctions topRight() et bottomLeft() contiennent respectivement la même différence par rapport à la vraie arête de droite et par rapport à la vraie arête inférieure.

Nous vous recommandons d'utiliser x() + width() et y() + height() pour trouver le vrai coin inférieur droit et d'éviter right() et bottom(). Une autre solution est d'utiliser QRectF : la classe QRectF définit un rectangle dans le plan en utilisant une précision décimale pour les coordonnées et les fonctions QRectF::right() et QRectF::bottom() retournent bien les vraies coordonnées de la droite et du bas du rectangle.

Il est également possible d'ajuster les coordonnées du rectangle en utilisant la fonction adjust() ainsi que de récupérer un nouveau rectangle basé sur les ajustements du rectangle original en utilisant la fonction adjusted(). Si la hauteur ou la largeur est négative, utilisez la fonction normalized() pour récupérer un rectangle dont les coins ont été échangés.

En outre, la classe QRect propose la fonction getCoords() qui extrait la position des coins supérieur gauche et inférieur droit du rectangle, ainsi que la fonction getRect() qui extrait la position du coin supérieur gauche du rectangle, avec sa largeur et sa hauteur. Utilisez les fonctions setCoords() et setRect() pour manipuler toutes les coordonnées et dimensions du rectangle en une seule fois.

Voir aussi QRectF et QRegion.

Fonctions membres

QRect::QRect ()

Construit un rectangle vide.

Voir aussi isNull().

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

Construit un rectangle avec les coins topLeft et bottomRight donnés.

Voir aussi setTopLeft() et setBottomRight().

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

Construit un rectangle avec le coin topLeft donné et la taille size donnée.

Voir aussi setTopLeft() et setSize().

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

Construit un rectangle dont le coin supérieur gauche a pour coordonnées (x, y) et qui a pour largeur width et pour hauteur height.

Voir aussi setRect().

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

Ajoute respectivement dx1, dy1, dx2 et dy2 aux coordonnées existantes du rectangle.

Voir aussi adjusted() et setRect().

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

Retourne un nouveau rectangle avec dx1, dy1, dx2 et dy2 ajoutés respectivement aux coordonnées existantes du rectangle.

Voir aussi adjust().

int QRect::bottom() const

Retourne l'ordonnée de l'arête inférieure. Notez que, pour des raisons historiques, cette fonctions retourne top() + height() - 1 ; utilisez y() + height() pour récupérer la vraie ordonnée.

Voir aussi setBottom(), bottomLeft() et bottomRight().

QPoint QRect::bottomLeft() const

Retourne la positon du coin inférieur gauche du rectangle. Notez que, pour des raisons historiques, cette fonction retourne QPoint(left(), top() + height() - 1).

Voir aussi setBottomLeft(), bottom() et left().

QPoint QRect::bottomRight() const

Retourne la position du coin inférieur droit du rectangle. Notez que, pour des raisons historiques, cette fonction retourne QPoint(left() + width() -1, top() + height() - 1).

Voir aussi setBottomRight(), bottom() et right().

QPoint QRect::center() const

Retourne le centre du rectangle.

Voir aussi moveCenter().

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

Retourne true si le point donné est à l'intérieur ou sur une arête du rectangle, sinon retourne false. Si l'argument proper vaut true, cette fonction ne renvoie true que si le point donné est à l'intérieur du rectangle (c'est-à-dire pas sur une arête).

Voir aussi intersects().

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

Il s'agit d'une fonction surchargée.

Retourne true si le point (x, y) est à l'intérieur ou sur une arête du rectangle, sinon retourne false. Si l'argument proper vaut true, cette fonction ne renvoie true que si le point donné est entièrement dans le rectangle (pas sur une arête).

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

Il s'agit d'une fonction surchargée.

Retourne true si le point (x, y) est à l'intérieur du rectangle, sinon retourne false.

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

Il s'agit d'une fonction surchargée.

Retourne true si le rectangle donné est à l'intérieur du rectangle, sinon retourne false. Si l'argument proper vaut true, cette fonction ne renvoie true que si le rectangle donné est entièrement dans le rectangle (pas sur une arête).

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

Extrait la position du coin supérieur gauche du rectangle vers *x1 et *y1 et la position du coin inférieur droit vers *x2 et*y2.

Voir aussi setCoords() et getRect().

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

Extrait la position du coin supérieur gauche du rectangle vers *x et *y et ses dimensions vers *width (la largeur) et *height (la hauteur).

Voir aussi setRect() et getCoords().

int QRect::height() const

Retourne la hauteur du rectangle.

Voir aussi setHeight(), width() et size().

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

Retourne l'intersection du rectangle avec le rectangle donné. Notez que r.intersected(s) est équivalent à r & s (voir operator&()).

Cette fonction a été introduite dans Qt 4.2.

Voir aussi intersects(), united() et operator&=().

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

Retourne true si le rectangle intersecte le rectangle donné (c'est-à-dire s'il y a au moins un pixel qui appartient aux deux rectangles), sinon retourne false.

Le rectangle correspondant à cette intersection peut-être récupéré avec la fonction intersected().

Voir aussi contains().

bool QRect::isEmpty() const

Retourne true si le rectangle est vide, sinon retourne false.

Un rectangle vide a left() > right() ou top() > bottom(). Un rectangle vide n'est pas valide (c'est-à-dire que isEmpty() == !isValid()).

Utilisez la fonction normalized() pour récupérer un rectangle où les coins sont échangés.

Voir aussi isNull(), isValid() et normalized().

bool QRect::isNull() const

Retourne true si le rectangle est un rectangle Null, sinon retourne false.

Un rectangle Null est un rectangle dont à la fois la hauteur et la largeur valent 0 (c'est-à-dire que right() == left() - 1 et bottom() == top() - 1). Un rectangle Null est également vide et, de fait, n'est pas valide.

Voir aussi isEmpty() et isValid().

bool QRect::isValid() const

Retourne true si le rectangle est valide, sinon retourne false.

Un rectangle valide est tel que left() < right() et top() < bottom(). Notez que les opérations complexes comme les intersections ne sont pas définies pour les rectangles non valides. Un rectangle valide n'est pas vide (c'est-à-dire, isValid() == !isEmpty()).

Voir aussi isNull(), isEmpty() et normalized().

int QRect::left() const

Retourne l'abscisse de l'arête gauche du rectangle. Équivalent à x().

Voir aussi setLeft(), topLeft() et bottomLeft().

void QRect::moveBottom(int y)

Déplace le rectangle verticalement, de façon à ce que l'arête inférieure du rectangle ait l'ordonnée y donnée. La taille du rectangle reste inchangée.

Voir aussi bottom(), setBottom() et moveTop().

void QRect::moveBottomLeft(const QPoint& position)

Déplace le rectangle, de façon à ce que son coin inférieur gauche soit à la position donnée. La taille du rectangle reste inchangée.

Voir aussi setBottomLeft(), moveBottom() et moveLeft().

void QRect::moveBottomRight(const QPoint& position)

Déplace le rectangle, de façon à ce que son coin inférieur droit soit à la position donnée. La taille du rectangle reste inchangée.

Voir aussi setBottomRight(), moveRight() et moveBottom().

void QRect::moveCenter(const QPoint& position)

Déplace le rectangle, de façon à ce que son centre soit à la position donnée. La taille du rectangle reste inchangée.

Voir aussi center().

void QRect::moveLeft(int x)

Déplace le rectangle horizontalement, de façon à ce que l'arête gauche du rectangle ait l'abscisse x donnée. La taille du rectangle reste inchangée.

Voir aussi left(), setLeft() et moveRight().

void QRect::moveRight(int x)

Déplace le rectangle horizontalement, de façon à ce que l'arête droite du rectangle ait l'abscisse x donnée. La taille du rectangle reste inchangée.

Voir aussi right(), setRight() et moveLeft().

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

Déplace le rectangle, de façon à ce que son coin supérieur gauche soit à la position (x,y) donnée. La taille du rectangle reste inchangée.

Voir aussi translate() et moveTopLeft().

void QRect::moveTo(const QPoint& position)

Déplace le rectangle, de façon à ce que son coin supérieur gauche soit à la position donnée. La taille du rectangle reste inchangée.

void QRect::moveTop(int y)

Déplace le rectangle verticalement, de façon à ce que l'arête supérieure du rectangle ait l'ordonnée y donnée. La taille du rectangle reste inchangée.

Voir aussi top(), setTop() et moveBottom().

void QRect::moveTopLeft(const QPoint& position)

Déplace le rectangle de façon à ce que son coin supérieur gauche soit à la position donnée. La taille du rectangle reste inchangée.

Voir aussi setTopLeft(), moveTop() et moveLeft().

void QRect::moveTopRight ( const QPoint & position )

Déplace le rectangle de façon à ce que son coin supérieur droit soit à la position donnée. La taille du rectangle reste inchangée.

Voir aussi setTopRight(), moveTop() et moveRight().

QRect QRect::normalized () const

Retourne un rectangle normalisé, c'est-à-dire un rectangle qui a une hauteur et une largeur non nulles.

Si width() < 0, la fonction échange les coins droits et gauches, de même pour les coins supérieurs et inférieurs si height() < 0.

Voir aussi isValid() et isEmpty().

int QRect::right () const

Retourne l'abscisse de l'arête droite du rectangle.

Notez que, pour des raisons historiques, cette fonction retourne left() + width() - 1. Utilisez x() + width() pour récupérer la vraie abscisse.

Voir aussi setRight(), topRight() et bottomRight().

void QRect::setBottom ( int y )

Définit l'ordonnée de l'arête inférieure du rectangle à l'ordonnée y donnée. Ceci peut changer la hauteur mais jamais l'arête supérieure du rectangle.

Voir aussi bottom() et moveBottom().

void QRect::setBottomLeft ( const QPoint & position )

Définit la position du coin inférieur gauche du rectangle à la position donnée. Ceci peut changer la taille mais jamais le coin supérieur droit du rectangle.

Voir aussi bottomLeft() and moveBottomLeft().

void QRect::setBottomRight ( const QPoint & position )

Définit la position du coin inférieur droit du rectangle à la position donnée. Ceci peut changer la taille mais jamais le coin supérieur gauche du rectangle.

Voir aussi bottomRight() et moveBottomRight().

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

Définit les coordonnées du coin supérieur gauche du rectangle à (x1,y1) et les coordonnées de son coin inférieur droit à (x2,y2).

Voir aussi coords(), getCoords() et setRect().

void QRect::setHeight ( int height )

Définit la hauteur du rectangle à la height donnée. L'arête inférieure est déplacée mais l'arête supérieure reste inchangée.

Voir aussi height() et setSize().

void QRect::setLeft ( int x )

Définit l'abscisse de l'arête gauche du rectangle à l'abscisse x donnée. Ceci peut changer la taille mais jamais l'arête droite du rectangle.

Équivalent à setX().

Voir aussi left() and moveLeft().

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

Définit les coordonnées du coin supérieur gauche du rectangle à (x, y), sa largeur à la width donnée et sa hauteur à la height donnée.

Voir aussi rect(), getRect() et setCoords().

void QRect::setRight ( int x )

Définit l'abscisse de l'arête droite du rectangle à l'abscisse x donnée. Ceci peut changer la largeur mais jamais l'arête gauche du rectangle.

Voir aussi right() et moveRight().

void QRect::setSize ( const QSize & size )

Définit la taille du rectangle à la size donnée. Le coin supérieur gauche n'est pas déplacé.

Voir aussi size(), setWidth() et setHeight().

void QRect::setTop ( int y )

Définit l'ordonnée de l'arête supérieure du rectangle à l'ordonnée y donnée. Ceci peut changer la hauteur mais jamais l'arête inférieure du rectangle.

Équivalent à setY().

Voir aussi top() et moveTop().

void QRect::setTopLeft ( const QPoint & position )

Définit le coin supérieur gauche du rectangle à la position donnée. Cela peut changer la taille mais cela ne changera jamais la position du coin inférieur droit du rectangle.

Voir aussi topLeft() et moveTopLeft().

void QRect::setTopRight ( const QPoint & position )

Définit le coin supérieur droit du rectangle à la position donnée. Cela peut changer la taille mais cela ne changera jamais la position du coin inférieur gauche du rectangle.

Voir aussi topRight() et moveTopRight().

void QRect::setWidth ( int width )

Définit la largeur du rectangle à la width donnée. L'arête de droite est déplacée mais l'arête de gauche reste inchangée.

Voir aussi width() et setSize().

void QRect::setX ( int x )

Définit l'abscisse de l'arête gauche du rectangle à l'abscisse x donnée. Ceci peut changer la taille mais jamais l'arête droite du rectangle.

Équivalent à setLeft().

Voir aussi x(), setY() et setTopLeft().

void QRect::setY ( int y )

Définit l'ordonnée de l'arête supérieure du rectangle à l'ordonnée y donnée. Ceci peut changer la hauteur mais jamais l'arête inférieure du rectangle.

Équivalent à setTop().

Voir aussi y(), setX() et setTopLeft().

QSize QRect::size () const

Retourne la taille du rectangle.

Voir aussi setSize(), width() et height().

int QRect::top () const

Retourne l'ordonnée de l'arête supérieure du rectangle. Équivalent à y().

Voir aussi setTop(), topLeft() et topRight().

QPoint QRect::topLeft () const

Retourne la position du coin supérieur gauche du rectangle.

Voir aussi setTopLeft(), top() et left().

QPoint QRect::topRight () const

Retourne la position du coin supérieur droit du rectangle. Notez que, pour des raisons historiques, cette fonction retourne QPoint(left() + width() -1, top()).

Voir aussi setTopRight(), top() et right().

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

Déplace le rectangle de dx selon l'axe x et de dy selon l'axe y, par rapport à sa position actuelle. Des valeurs positives de dx et dy déplacent le rectangle vers la droite et le bas.

Voir aussi moveTopLeft(), moveTo() et translated().

void QRect::translate ( const QPoint & offset )

Il s'agit d'une fonction surchargée.

Déplace le rectangle de offset.x() selon l'axe x et de offset.y() selon l'axe y, par rapport à sa position actuelle.

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

Retourne une copie du rectangle translatée de dx selon l'axe x et de dy selon l'axe y, par rapport à sa position actuelle. Des valeurs positives de dx et dy déplacent le rectangle vers la droite et le bas.

Voir aussi translate().

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

Il s'agit d'une fonction surchargée.

Retourne une copie du rectangle translatée de offset.x() selon l'axe x et de offset.y() selon l'axe y, par rapport à sa position actuelle.

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

Retourne le rectangle englobant ce rectangle et le rectangle donné.

Cette fonction a été introduite dans Qt 4.2.

Voir aussi intersected().

int QRect::width () const

Retourne la largeur du rectangle.

Voir aussi setWidth(), height() et size().

int QRect::x () const

Retourne l'abscisse de l'arête gauche du rectangle. Équivalent à left().

Voir aussi setX(), y() et topLeft().

int QRect::y () const

Retourne l'ordonnée de l'arête supérieure du rectangle. Équivalent à top().

Voir aussi setY(), x() et topLeft().

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

Retourne l'intersection du rectangle avec le rectangle donné. Retourne un rectangle vide s'il n'y a pas d'intersection.

Voir aussi operator&=() et intersected().

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

Intersecte le rectangle avec le rectangle donné.

Voir aussi intersected() et operator&().

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

Retourne le rectangle englobant ce rectangle et le rectangle donné.

Voir aussi operator|=() et united().

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

Réunit ce rectangle et le rectangle donné.

Voir aussi united() et operator|().

En relation mais non membres de la classe

bool operator!=(const QRect& r1, const QRect& r2)

Retourne true si les rectangles r1 et r2 sont différents, sinon retourne false.

QDataStream & operator<< ( QDataStream & stream, const QRect & rectangle )

Écrit le rectangle donné dans le flux stream donné et retourne une référence sur le flux.

Voir aussi sérialisation des types de données Qt.

bool operator== ( const QRect & r1, const QRect & r2 )

Retourne true si les rectangles r1 et r2 sont égaux, sinon retourne false.

QDataStream & operator>> ( QDataStream & stream, QRect & rectangle )

Lit un rectangle à partir du flux stream donné, la place dans le rectangle donné et retourne une référence sur le flux.

Voir aussi sérialisation des types de données Qt.

Remerciements

Merci à Abdelhafid Hafidi et Nicolas Carion pour la traduction, à Jonathan Courtois, Thibaut Cuvelier et Maxime Gault pour la relecture !