QPen

La classe QPen (pinceau) définit la façon dont un QPainter doit dessiner les lignes et les bordures des formes. Plus d'informations...

#include <QPen>

Voir la position dans l'arbre des classes.

Description détaillée

La classe QPen (pinceau) définit la façon dont un QPainter doit dessiner les lignes et les bordures des formes.

Un pinceau possède un style, une largeur, une brosse, un style d'extrémité et un style de jointure.

Le style de pinceau définit le type de ligne. La brosse est utilisée pour remplir les traits générés par le pinceau. On utilise la classe QBrush pour spécifier les styles de remplissage. Le style d'extrémité détermine la façon dont les terminaisons de lignes sont dessinées par QPainter, alors que le style de jointure décrit la façon dont les jointures entre deux lignes sont dessinées. La largeur de pinceau peut être spécifiée soit sous forme d'entier (width()), soit de flottant (widthF()). Une largeur de zéro indique un pinceau cosmétique - cela signifie que le pinceau sera toujours dessiné avec une largeur d'un pixel, indépendamment de la transformation affectée au QPainter.

Les différents paramètres peuvent être facilement modifiés en utilisant les fonctions correspondantes setStyle(), setWidth(), setBrush(), setCapStyle() et setJoinStyle() (on note que le pinceau du QPainter doit être réinitialisé lorsque les propriétés du pinceau sont modifiées).

Par exemple :

 QPainter painter(this);
 QPen pen(Qt::green, 3, Qt::DashDotLine, Qt::RoundCap, Qt::RoundJoin);
 painter.setPen(pen);

qui est équivalent à

 QPainter painter(this);
 QPen pen();  // crée un pinceau par défaut
 
 pen.setStyle(Qt::DashDotLine);
 pen.setWidth(3);
 pen.setBrush(Qt::green);
 pen.setCapStyle(Qt::RoundCap);
 pen.setJoinStyle(Qt::RoundJoin);
 
 painter.setPen(pen);

Le pinceau par défaut est une brosse noire pleine, de largeur 0, avec un style d'extrémité carré (Qt::SquareCap) et un style de jointure biseauté (Qt::BevelJoin).

De plus QPen fournit les fonctions utilitaires color() et setColor() pour respectivement extraire et spécifier la couleur de la brosse du pinceau. Les pinceaux peuvent être aussi comparés et sérialisés.

Pour plus d'informations sur le dessin en général, voir la documentation du système de dessin.

Style de pinceau

Qt fournit plusieurs styles prédéfinis représentés par l'énumération Qt::PenStyle :

Qt::SolidLine	Qt::DashLine	Qt::DotLine
Qt::DashDotLine	Qt::DashDotDotLine	Qt::CustomDashLine

On utilise simplement la fonction setStyle() pour convertir le style de pinceau vers un des styles prédéfinis, sauf le style Qt::CustomDashLine sur lequel nous reviendrons. Spécifier le style Qt::NoPen demande au QPainter ne de pas tracer de ligne ou de bordure. Le style de pinceau par défaut est Qt::SolidLine.

Depuis Qt 4.1 il est aussi possible de spécifier un motif de pointillés personnalisé en utilisant la fonction setDashPattern() qui convertit implicitement le style du pinceau à Qt::CustomDashLine. L'argument motif, un QVector, est spécifié comme un nombre pair d'entrées de type qreal où les entrées 1, 3, 5... sont les traits et 2, 4, 6... sont les espaces. Par exemple, le motif personnalisé ci-dessus est créé par le code suivant :

 QPen pen;
 QVector<qreal> dashes;
 qreal space = 4;
 
 dashes << 1 << space << 3 << space << 9 << space
            << 27 << space << 9 << space;
 
 pen.setDashPattern(dashes);

On note que le motif de pointillés est spécifié en unité de largeur de pinceau, par exemple une longueur de trait de 5 en largeur 10 a une longueur de 50 pixels.

Le motif de pointillés courant peut être lu en utilisant la fonction dashPattern(). On utilise la fonction isSolid() pour déterminer si le pinceau est plein ou non.

Style d'extrémité

Le style d'extrémité définit la façon dont les points terminaux des lignes sont dessinés par QPainter. Le style d'extrémité ne s'applique qu'aux lignes larges, c'est-à-dire de largeur 1 ou plus. L'énumération Qt::PenCapStyle fournit les styles suivants :

Qt::SquareCap	Qt::FlatCap	Qt::RoundCap

Le style Qt::SquareCap est une fin de ligne carrée couvrant le point terminal et s'étendant au delà de la moitié de la largeur de ligne. Le style Qt::FlatCap est une fin de ligne carrée ne couvrant pas le point terminal. Et le style Qt::RoundCap est une fin de ligne ronde couvrant le point terminal.

La valeur par défaut est Qt::SquareCap.

Le fait que les points terminaux soient dessinés lorsque la largeur de pinceau est 0 ou 1 dépend du style de terminaison. Avec Qt::SquareCap ou Qt::RoundCap ils sont dessinés, avec Qt::FlatCap ils ne ne sont pas.

Style de jointure

Le style de jointure définit la façon dont les jointures entre deux lignes connectées peuvent être dessinées par QPainter. Le style de jointure ne s'applique qu'aux lignes larges, c'est-à-dire de largeur 1 ou plus. L'énumération Qt::PenJoinStyle fournit les styles suivants :

Qt::BevelJoin	Qt::MiterJoin	Qt::RoundJoin

Le style Qt::BevelJoin remplit l'encoche triangulaire entre les deux lignes. Le style Qt::MiterJoin étend les lignes pour qu'elles se rencontrent avec un angle, et le style Qt::RoundJoin crée un arc circulaire entre les deux lignes.

La valeur par défaut est Qt::BevelJoin.

Lorsque le style Qt::MiterJoin est appliqué, il est possible d'utiliser la fonction setMiterLimit() pour spécifier jusqu'où la jointure peut être étendue au delà du point de jointure. La miterLimit() est utilisée pour réduire les artefacts entre les jointures lorsque les lignes sont presque parallèles.

La miterLimit() doit être spécifiée en unités de largeur de pinceau, par exemple une limite de 5 avec une largeur de 10 a une longueur de 50 pixels. La limite par défaut est 2, c'est-à-dire deux fois la largeur de pinceau en pixels.

La démo de tracé de chemin présente les motifs de pointillés intégrés de Qt et montre la façon dont les motifs personnalisés peuvent être utilisés pour étendre les motifs disponibles.

Voir aussi QPainter, QBrush, la démo de tracé de chemin et l'exemple Scribble.

Fonctions membres

QPen::QPen ()

Construit un pinceau par défaut (ligne noire pleine de largeur 0).

QPen::QPen ( Qt::PenStyle style )

Construit un pinceau noir de largeur 0 et de style donné.

Voir aussi setStyle().

QPen::QPen ( const QColor & color )

Construit un pinceau plein de largeur 0 de la couleur color donnée.

Voir aussi setBrush() et setColor().

QPen::QPen ( const QBrush & brush, qreal width, Qt::PenStyle style = Qt::SolidLine, Qt::PenCapStyle cap = Qt::SquareCap, Qt::PenJoinStyle join = Qt::BevelJoin )

Construit un pinceau avec la brosse brush, la largeur width, le style de pinceau style, le style d'extrémité cap et le style de jointure join spécifiés.

Voir aussi setBrush(), setWidth(), setStyle(), setCapStyle() et setJoinStyle().

QPen::QPen ( const QPen & pen )

Construit un pinceau en copiant le pinceau pen donné.

QPen::~QPen ()

Détruit le pinceau.

QBrush QPen::brush () const

Renvoie la brosse utilisée pour remplir les tracés générés par ce pinceau.

Voir aussi setBrush().

Qt::PenCapStyle QPen::capStyle () const

Renvoie le style d'extrémité du pinceau.

Voir aussi setCapStyle() et Cap Style.

QColor QPen::color () const

Renvoie la couleur de la brosse de ce pinceau.

Voir aussi brush() et setColor().

qreal QPen::dashOffset () const

Renvoie l'offset des pointillés du pinceau.

Voir aussi setDashOffset().

QVector<qreal> QPen::dashPattern () const

Renvoie le motif de pointillés du pinceau.

Voir aussi setDashPattern(), style() et isSolid().

bool QPen::isCosmetic () const

Renvoie true si le pinceau est cosmétique ; sinon renvoie false.

Les pinceaux cosmétiques sont utilisés pour les tracés ayant une largeur constante indépendamment des transformations appliquées au QPainter avec lequel ils sont utilisés. Dessiner une forme avec un pinceau cosmétique garantit que son contour aura la même épaisseur à différents facteurs d'échelle.

Un pinceau de largeur zéro est cosmétique par défaut ; les pinceaux de largeur différente de zéro sont non-cosmétiques.

Voir aussi setCosmetic() et widthF().

bool QPen::isSolid () const

Renvoie true si le pinceau est plein ; sinon renvoie false.

Voir aussi style() et dashPattern().

Qt::PenJoinStyle QPen::joinStyle () const

Renvoie le style de jointure du pinceau.

Voir aussi setJoinStyle() et Join Style.

qreal QPen::miterLimit () const

Renvoie la limite de mitre du pinceau. La limite n'est significative que si le style de jointure est Qt::MiterJoin.

Voir aussi setMiterLimit() et Join Style.

void QPen::setBrush ( const QBrush & brush )

Spécifie brush comme brosse utilisée pour remplir les tracés faits avec ce pinceau.

Voir aussi brush() et setColor().

void QPen::setCapStyle ( Qt::PenCapStyle style )

Spécifie le style donné comme style d'extrémité. La valeur par défaut est Qt::SquareCap.

Voir aussi capStyle() et Cap Style.

void QPen::setColor ( const QColor & color )

Spécifie color comme couleur de brosse de ce pinceau.

Voir aussi setBrush() et color().

void QPen::setCosmetic ( bool cosmetic )

Rend le pinceau cosmétique ou non-cosmétique, en fonction de la valeur de cosmetic.

Voir aussi isCosmetic().

void QPen::setDashOffset ( qreal offset )

Fixe l'offset de pointillés (le point de départ du motif de pointillés) pour ce pinceau à la valeur offset spécifiée. L'offset est mesuré dans la même unité que celle utilisée pour spécifier le motif de pointillés.

Par exemple, un motif où chaque trait est long de quatre unités, suivi d'un espace de deux unités, va commencer par le trait lorsque la ligne est dessinée. Cependant, si l'offset de pointillés est fixé à 4.0, les lignes vont commencer par l'espace. Les valeurs de l'offset jusqu'à 4.0 feront que la ligne commencera par une partie du trait et une valeur d'offset entre 4.0 et 6.0 feront que la ligne commencera par un espace.

Note : ceci convertit implicitement le style du pinceau à Qt::CustomDashLine.

Voir aussi dashOffset().

void QPen::setDashPattern ( const QVector<qreal> & pattern )

Spécifie la valeur pattern comme motif de pointillés du pinceau. Ceci convertit implicitement le style du pinceau à Qt::CustomDashLine.

Le motif est spécifié comme un nombre pair d'entrées où les entrées 1, 3, 5... sont les traits et 2, 4, 6... sont les espaces. Par exemple :

QPen pen; QVector<qreal> dashes; qreal space = 4; dashes << 1 << space << 3 << space << 9 << space << 27 << space << 9 << space; pen.setDashPattern(dashes);

Le motif de pointillés est spécifié en unité de largeur de pinceau, par exemple une longueur de trait de 5 en largeur 10 a une longueur de 50 pixels. On note qu'un pinceau de largeur zéro est équivalent à un pinceau cosmétique de largeur 1 pixel.

Chaque trait est aussi affecté par les styles d'extrémités, et donc un trait de longueur 1 avec une extrémité carrée s'étendra de 5 pixels dans chaque direction, avec une longueur résultante totale de 2.

On note que le style d'extrémité par défaut est Qt::SquareCap, ce qui signifie qu'une fin de ligne carrée couvre les points terminaux et s'étend au delà de la moitié de la largeur de la ligne.

Voir aussi setStyle(), dashPattern(), setCapStyle() et setCosmetic().

void QPen::setJoinStyle ( Qt::PenJoinStyle style )

Spécifie style comme style de jointure du pinceau. La valeur par défaut est Qt::BevelJoin.

Voir aussi joinStyle() et Join Style.

void QPen::setMiterLimit ( qreal limit )

Spécifie limit comme limite de mitre du pinceau.

La limite de mitre correspond à la distance jusqu'à laquelle la jointure peut s'étendre au delà du point de jointure. Elle est utilisée pour réduire les artefacts entre les jointures lorsque les lignes sont presque parallèles.

Cette valeur n'a d'effet que si le style est Qt::MiterJoin. Elle doit être spécifiée en unités de largeur de pinceau, par exemple une limite de 5 avec une largeur de 10 a une longueur de 50 pixels. La limite par défaut est 2, c'est-à-dire deux fois la largeur de pinceau en pixels.

Voir aussi miterLimit(), setJoinStyle() et Join Style.

void QPen::setStyle ( Qt::PenStyle style )

Spécifie style comme style du pinceau.

Voir la documentation Qt::PenStyle pour la liste des styles disponibles. Depuis Qt 4.1 il est aussi possible de spécifier un motif de pointillés personnalisé en utilisant la fonction setDashPattern() qui convertit implicitement le style du pinceau à Qt::CustomDashLine.

Note : cette fonction réinitialise l'offset de pointillés à zéro.

Voir aussi style() et Pen Style.

void QPen::setWidth ( int width )

Fixe la largeur du pinceau à width pixels en précision entière.

Une largeur de zéro indique un pinceau cosmétique. Cela signifie que le pinceau sera toujours dessiné avec une largeur d'un pixel, indépendamment de la transformation affectée au QPainter.

Les largeurs de pinceau négatives ne sont pas gérées.

Voir aussi setWidthF() et width().

void QPen::setWidthF ( qreal width )

Fixe la largeur du pinceau à width pixels en précision flottante.

Une largeur de zéro indique un pinceau cosmétique. Cela signifie que le pinceau sera toujours dessiné avec une largeur d'un pixel, indépendamment de la transformation affectée au QPainter.

Les largeurs de pinceau négatives ne sont pas gérées.

Voir aussi setWidth() et widthF().

Qt::PenStyle QPen::style () const

Renvoie le style de pinceau.

Voir aussi setStyle() et Pen Style.

int QPen::width () const

Renvoie la largeur du pinceau en précision entière.

Voir aussi setWidth() et widthF().

qreal QPen::widthF () const

Renvoie la largeur du pinceau en précision flottante.

Voir aussi setWidthF() et width().

QPen::operator QVariant () const

Renvoie le pinceau sous forme d'un QVariant.

bool QPen::operator!= ( const QPen & pen ) const

Renvoie true si le pinceau est différent du pinceau pen donné ; sinon renvoie false. Deux pinceaux sont différents s'ils ont des styles, largeurs ou couleurs différents.

Voir aussi operator==().

QPen & QPen::operator= ( const QPen & pen )

Affecte le pinceau pen à ce pinceau et renvoie une référence au pinceau (this).

bool QPen::operator== ( const QPen & pen ) const

Renvoie true si le pinceau est égal au pincau pen donné ; sinon renvoie false. Deux pinceaux sont égaux s'ils ont des styles, largeurs et couleurs égaux.

Voir aussi operator!=().

En relation mais non membres de la classe

QDataStream & operator<< ( QDataStream & stream, const QPen & pen )

Écrit le pinceau pen donné dans stream et renvoie une référence à stream.

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

QDataStream & operator>> ( QDataStream & stream, QPen & pen )

Lit un pinceau depuis stream dans le pinceau pen donné et renvoie une référence à stream.

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

Remerciements

Merci à Ilya Diallo pour la traduction ainsi qu'à Lo?c Leguay, Jonathan Courtois et Jacques Thery pour leur relecture !