QGraphicsEffect

La classe QGraphicsEffect est la classe de base de tous les effets graphiques. Plus d'informations...

#include <QGraphicsEffect>

Voir la position dans l'arbre des classes.

Héritage

Hérite de QObject.

Hérité par QGraphicsBlurEffect, QGraphicsColorizeEffect, QGraphicsDropShadowEffect et QGraphicsOpacityEffect.

Cette classe a été introduite dans Qt 4.6.

Description détaillée

La classe QGraphicsEffect est la classe de base de tous les effets graphiques.

Les effets altèrent l'apparence des éléments par hooking dans le pipeline de rendu et d'exploitation entre la source (par exemple, un QGraphicsPixmapItem) et le dispositif cible (par exemple, le viewport d'un QGraphicsView). Les effets peuvent être désactivés par l'appel de setEnabled(false). Si les effets sont désactivés, la source est rendue directement.

Pour ajouter un effet visuel à un QGraphicsItem, par exemple, vous pouvez utiliser l'un des effets standards ou bien créer votre propre effet en sous-classant QGraphicsEffect. L'effet peut être installé sur l'élément en utilisant QGraphicsItem::setGraphicsEffect().

Qt fournit les effets standards suivants :

• QGraphicsBlurEffect - brouille l'élément avec un radius donné ;
• QGraphicsDropShadowEffect - effectue le rendu d'une ombre portée derrière l'élément ;
• QGraphicsColorizeEffect - effectue le rendu de l'élément avec des teintes d'une couleur donnée ;
• QGraphicsOpacityEffect - effectue le rendu de l'élément avec une opacité.

Pour plus d'informations sur la manière d'utiliser chaque effet, se référer à la documentation spécifique de chaque effet.

Pour créer son propre effet, il s'agit de créer une sous-classe de QGraphicsEffect (ou de tout autre effet existant) et de ré-implémenter la fonction virtuelle draw(). Cette fonction est appelée à chaque fois que l'effet nécessite d'être redessiné. La fonction draw() prend en argument le painter avec lequel dessiner. Pour plus d'information, se référer à la documentation de draw(). Dans la fonction draw(), il est possible d'appeler sourcePixmap() pour récupérer un pixmap de la source de l'effet graphique sur lequel il est alors possible de traiter.

Si l'effet change, la fonction update() peut être utilisée pour demander à ce qu'il y ait une nouvelle peinture. Si l'effet personnalisé change le rectangle de limites de la source, par exemple, un effet de lueur radiale nécessitant une marge supplémentaire, il est possible de ré-implémenter la fonction virtuelle boundingRectFor() et d'appeler updateBoundingRect() pour notifier le framework à chaque fois que ce rectangle change. La fonction virtuelle sourceChanged() est appelée pour prévenir les effets que la source a changé d'une certaine manière - par exemple, si la source est un QGraphicsRectItem et que son paramètre rectangle a changé.

Voir aussi QGraphicsItem::setGraphicsEffect() et QWidget::setGraphicsEffect().

Type

enum QGraphicsEffect::ChangeFlagflags QGraphicsEffect::ChangeFlags

Cette énumération décrit ce qui a changé dans QGraphicsEffectSource.

Le type ChangeFlags est un typedef de QFlags<ChangeFlag>. Il stocke des combinaisons OU des valeurs de ChangeFlag.

enum QGraphicsEffect::PixmapPadMode

Cette énumération décrit comment le pixmap retourné depuis sourcePixmap doit être entouré.

Propriétés

enabled : bool

Cette propriété définit si l'effet est activé ou non.

Si un effet est désactivé, la source sera rendue normalement sans interférence en provenance de l'effet. Si l'effet est activé, la source sera rendue avec l'effet appliqué.

Cette propriété est activée par défaut.

En utilisant cette propriété, vous pouvez désactiver certains effets sur les plateformes lentes afin de garantir que l'interface utilisateur reste répondante.

Fonctions d'accès

bool isEnabled () const

void setEnabled ( bool enable )

Signal de notification :

void enabledChanged ( bool enabled )

Fonctions membres

QGraphicsEffect::QGraphicsEffect ( QObject * parent = 0 )

Construit une nouvelle instance de QGraphicsEffect ayant le parent spécifié.

QGraphicsEffect::~QGraphicsEffect () [virtual]

Retire l'effet de la source et détruit l'effet graphique.

QRectF QGraphicsEffect::boundingRect () const

Retourne le rectangle effectif de limites de cet effet, c'est-à-dire, le rectangle de limites de la source dans les coordonnées du dispositif, ajusté par toute marge appliquée par l'effet lui-même.

Voir aussi boundingRectFor() et updateBoundingRect().

QRectF QGraphicsEffect::boundingRectFor ( const QRectF & rect ) const [virtual]

Retourne le rectangle effectif de limites de cet effet, donné par le rect fourni dans les coordonnées du dispositif. Lors de la réécriture d'un effet personnalisé, il est nécessaire d'appeler updateBoundingRect() à chaque fois que des paramètres changent, ce qui peut faire en sorte que cette fonction retourne une valeur différente.

Voir aussi sourceBoundingRect().

void QGraphicsEffect::draw ( QPainter * painter ) [pure virtual protected]

Cette fonction pure virtuelle dessine l'effet et est appelée à chaque fois que la source nécessite d'être dessinée.

Réimplémentez cette fonction dans une sous-classe de QGraphicsEffect pour fournir l'implémentation de dessin de l'effet, en utilisant painter.

Par exemple :

 MyGraphicsEffect::draw(QPainter *painter)
 {
     ...
     QPoint offset;
     if (sourceIsPixmap()) {
         // No point in drawing in device coordinates (pixmap will be scaled anyways).
         const QPixmap pixmap = sourcePixmap(Qt::LogicalCoordinates, &offset);
         ...
         painter->drawPixmap(offset, pixmap);
     } else {
         // Draw pixmap in device coordinates to avoid pixmap scaling;
         const QPixmap pixmap = sourcePixmap(Qt::DeviceCoordinates, &offset);
         painter->setWorldTransform(QTransform());
         ...
         painter->drawPixmap(offset, pixmap);
     }
     ...
 }

Cette fonction ne doit pas être appelée explicitement par l'utilisateur dans le sens où elle est uniquement conçue pour être réimplémentée.

void QGraphicsEffect::drawSource ( QPainter * painter ) [protected]

Dessine directement la source en utilisant le painter donné.

Cette fonction devrait uniquement être appelée depuis QGraphicsEffect::draw().

Par exemple :

 MyGraphicsOpacityEffect::draw(QPainter *painter)
 {
     // Fully opaque; draw directly without going through a pixmap.
     if (qFuzzyCompare(m_opacity, 1)) {
         drawSource(painter);
         return;
     }
     ...
 }

Voir aussi QGraphicsEffect::draw().

void QGraphicsEffect::enabledChanged ( bool enabled ) [signal]

Ce signal est émis à chaque fois que l'effet est activé ou désactivé. Le paramètre enabled définit si l'effet est activé ou non.

Voir aussi isEnabled().

QRectF QGraphicsEffect::sourceBoundingRect ( Qt::CoordinateSystem system = Qt::LogicalCoordinates ) const [protected]

Retourne le rectangle de limites de la source mappée au system donné.

L'appel de cette fonction avec Qt::DeviceCoordinates à l'extérieur de QGraphicsEffect::draw() donnera des résultats indéterminés puisqu'il n'y a pas de contexte de dispositif disponible.

Voir aussi draw().

void QGraphicsEffect::sourceChanged ( ChangeFlags flags ) [virtual protected]

Cette fonction virtuelle est appelée par QGraphicsEffect pour notifier à l'effet que la source a changé. Si l'effet applique un cache, alors ce cache devra être purgé afin de refléter la nouvelle apparence de la source.

Le paramètre flags décrit ce qui a changé.

bool QGraphicsEffect::sourceIsPixmap () const [protected]

Retourne true si la source effective est un pixmap, par exemple un QGraphicsPixmapItem.

Cette fonction est pratique pour l'optimisation. Par exemple, il n'y a pas de particularité dans le dessin de la source dans les coordonnées du dispositif permettant d'éviter la mise à l'échelle du pixmap, si cette fonction retourne true - le pixmap source sera échelonné de toute manière.

QPixmap QGraphicsEffect::sourcePixmap ( Qt::CoordinateSystem system = Qt::LogicalCoordinates, QPoint * offset = 0, PixmapPadMode mode = PadToEffectiveBoundingRect ) const [protected]

Retourne un pixmap avec la source peinte à l'intérieur.

Le system spécifie le système de coordonnées à utiliser pour la source. Le paramètre optionnel offset retourne l'offset où le pixmap doit être peint lors de l'utilisation du painter actuel. Pour contrôler la manière dont le pixmap est entouré, utilisez le paramètre mode.

Le pixmap retourné est rattaché au rectangle actuel du peintre du dispositif lorsque system est Qt::DeviceCoordinates.

L'appel de cette fonction avec Qt::DeviceCoordinates à l'extérieur de QGraphicsEffect::draw() donnera des résultats indéterminés puisqu'il n'y a pas de contexte de dispositif disponible.

Voir aussi draw() et boundingRect().

void QGraphicsEffect::update () [slot]

Demande à ce que l'effet soit redessiné. Appelez cette fonction à chaque fois que l'effet nécessite d'être redessiné. Cette fonction ne redessine pas la source.

Voir aussi updateBoundingRect().

void QGraphicsEffect::updateBoundingRect () [protected]

Cette fonction notifie le framework d'effets lorsque le rectangle de limites de l'effet a changé. En tant qu'auteur de l'effet personnalisé, vous devez appeler cette fonction à chaque fois que vous changez un paramètre qui va engendrer le retour de boundingRectFor() d'une valeur différente.

Cette fonction appellera update() si nécessaire.

Voir aussi boundingRectFor(), boundingRect() et sourceBoundingRect().

Remerciements

Merci à Louis du Verdier pour la traduction et à Dimitry Ernot, Jonathan Courtois ainsi qu'à Jacques Thery pour leur relecture !