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 !