QGraphicsLayout

La classe QGraphicsLayout fournit une classe de base pour tous les layouts dans la vue graphique. Plus d'informations...

#include <QGraphicsLayout>

Voir la position dans l'arbre des classes.

Héritage

Hérite de QGraphicsLayoutItem.

Hérité par QGraphicsAnchorLayout, QGraphicsGridLayout et QGraphicsLinearLayout.

La classe a été introduite dans Qt 4.4.

Description détaillée

La classe QGraphicsLayout fournit une classe de base pour tous les layouts dans la vue graphique.

La classe QGraphicsLayout est une classe abstraite qui définit une API virtuelle pour l'arrangement des QGraphicsWidget enfants et autres objets QGraphicsLayoutItem d'un QGraphicsWidget. Un QGraphicsWidget décharge les responsabilités à un QGraphicsLayout à travers QGraphicsWidget::setLayout(). Si le widget est redimensionné, le layout va automatiquement réorganiser les enfants du widget. La classe QGraphicsLayout hérite de QGraphicsLayoutItem, ce qui permet d'être pris en charge par n'importe quel layout, même ses propres sous-classes.

Créer un layout personnalisé

Vous pouvez utiliser QGraphicsLayout comme base pour créer votre propre layout (par exemple, un diagramme), mais il est d'usage d'utiliser une de ses sous-classes à la place - QGraphicsLinearLayout ou QGraphicsGridLayout. Lors de la création d'un layout personnalisé, il faut au moins réimplémenter les fonctions suivantes :

Pour plus de détails sur la façon d'implémenter chaque fonction, référez-vous à leur documentation.

Chaque layout définit sa propre API pour arranger les éléments widgets et layout. Par exemple, avec un layout en grille, vous avez besoin d'un index de colonne et de ligne avec un espacement optionnel entre les colonnes et les lignes, un alignement et plus encore. Par contre, un layout linéaire requiert un simple index de ligne ou de colonne pour positionner ses éléments. Pour un layout en grille, l'ordre d'insertion n'affecte pas le layout, contrairement au layout linéaire où l'ordre est essentiel. Lors de la création de votre sous-classe, vous êtes libre de choisir la méthode qui convient le mieux pour votre layout.

Activer le layout

Lorsque la géométrie du layout change, QGraphicsLayout réarrange immédiatement tous les éléments contenus en appelant la fonction setGeometry() pour chaque élément. Ce réarrangement est appelé activer le layout.

QGraphicsLayout met à jour sa propre géométrie pour correspondre au contentsRect() du QGraphicsLayoutItem qu'il gère. Cela va donc automatiquement réarranger tous les éléments lorsque le widget est redimensionné. QGraphicsLayout met les tailles des éléments gérés en mémoire pour éviter d'appeler setGeometry() trop souvent.

Note : un QGraphicsLayout va avoir la même géométrie que le contentsRect() du widget (pas du layout) auquel il est attaché.

Activer le layout implicitement

Le layout peut être activé implicitement en utilisant l'une de ces deux méthodes : activate() ou invalidate(). L'appel à activate() active le layout immédiatement. Au contraire, l'appel à invalidate() est temporisé, car il envoie un événement LayoutRequest au widget géré. À cause de la compression des événements, activate() va être appelée une seule fois après vérification à la sortie de la boucle événementielle. Cela est référencé comme une invalidation du layout. L'invalidation du layout invalide aussi les informations en cache. De plus, la fonction invalidate() est une fonction virtuelle. Donc, vous pouvez invalider votre propre cache dans une sous-classe de QGraphicsLayout en réimplémentant cette fonction.

Gestion des événements

QGraphicsLayout surveille les événements des widgets qu'il gère à travers le gestionnaire d'événements virtuel widgetEvent(). Lorsque le layout est assigné à un widget, tous les événements délivrés aux widgets sont d'abord traités par widgetEvent(). Cela permet au layout d'être informé d'importants changements d'état du widget comme les changements de visibilité ou les changements de direction du layout.

Gestion des marges

Les marges d'un QGraphicsLayout peuvent être modifiées en reimplémentant setContentsMargins() et getContentsMargins().

Fonctions membres

QGraphicsLayout::QGraphicsLayout ( QGraphicsLayoutItem * parent = 0 )

Construit un objet QGraphicsLayout.

Le parent est passé au constructeur de QGraphicsLayoutItem et isLayout du QGraphicsLayoutItem est définie à true.

Si parent est un QGraphicsWidget, le layout va être intégré à ce widget. (Notez que l'intégration du layout dans le widget va supprimer celui précédemment installé.)

QGraphicsLayout::~QGraphicsLayout ()

Détruit l'objet QGraphicsLayout.

void QGraphicsLayout::activate ()

Active le layout, causant le réarrangement immédiat de tous les éléments dans le layout. Cette fonction est basée sur l'appel de count() et itemAt() et appelle ainsi, séquentiellement, setGeometry() pour tous les éléments. Lors de l'activation, le layout va réajuster sa géométrie au contentsRect() de son parent. Le parent va alors invalider n'importe lequel de ses layouts.

Si la fonction est appelée dans une séquence ou récursivement, par exemple, par l'un des éléments arrangés en réponse à son redimensionnement, elle ne va rien faire.

Notez que le layout est libre d'utiliser une mémoire cache pour la géométrie afin d'optimiser le processus. Pour forcer l'invalidation de ce cache, vous pouvez appeler invalidate() avant activate().

Voir aussi invalidate().

void QGraphicsLayout::addChildLayoutItem ( QGraphicsLayoutItem * layoutItem ) [protected]

La fonction est une fonction de commodité fournie pour les layouts personnalisés et va parcourir tous les éléments du layout pour raffiner les éléments graphiques au plus proche parent QGraphicsWidget du layout.

Si le layout layoutItem est déjà intégré dans un layout différent, il va être retiré de ce layout.

Si les layouts personnalisés nécessitent un comportement spécial, ils peuvent ignorer l'utilisation de cette fonction et réimplémenter leur propre comportement.

Cette fonction a été introduite dans Qt 4.6.

Voir aussi graphicsItem().

int QGraphicsLayout::count () const [pure virtual]

Cette fonction virtuelle pure doit être réimplémentée dans les sous-classes de QGraphicsLayout afin de retourner le nombre d'éléments dans le layout.

La sous-classe est libre de définir la façon de conserver les éléments.

Voir aussi itemAt() et removeAt().

void QGraphicsLayout::getContentsMargins ( qreal * left, qreal * top, qreal * right, qreal * bottom ) const [virtual]

Réimplémentation de QGraphicsLayoutItem::getContentsMargins().

void QGraphicsLayout::invalidate () [virtual]

Nettoie toute information de géométrie ou de taille mise en cache dans le layout et envoie l'événement LayoutRequest au parent QGraphicsLayoutItem géré.

Voir aussi activate() et setGeometry().

bool QGraphicsLayout::isActivated () const

Retourne true si le layout est actuellement activé ; sinon, retourne false. Si le layout est activé, cela signifie qu'il est actuellement en train de réarranger ses éléments (par exemple, la fonction activate() a été appelée et n'a pas encore fini).

Voir aussi activate() et invalidate().

QGraphicsLayoutItem * QGraphicsLayout::itemAt ( int i ) const [pure virtual]

Cette fonction virtuelle pure doit être réimplémentée dans les sous-classes de QGraphicsLayout pour retourner un pointeur sur l'élément à l'index i. La réimplementation peut supposer que i est valide (qu'il respecte la valeur de count()). Cette fonction et la fonction count() ont été créées pour permettre l'itération de tous les éléments du layout.

La sous-classe est libre de décider de la façon de conserver les éléments et l'arrangement visuel n'est pas forcé de correspondre à cette fonction.

Voir aussi count() et removeAt().

void QGraphicsLayout::removeAt ( int index ) [pure virtual]

Cette fonction virtuelle pure doit être réimplémentée dans une sous-classe de QGraphicsLayout pour enlever l'élément à index. La réimplémentation peut supposer que index est valide (qu'il respecte la valeur de count()).

L'implémentation doit s'assurer que le parentLayoutItem() de l'élément enlevé ne pointe plus sur ce layout, du moment que l'élément est considéré comme hiérarchiquement retiré du layout.

Si le layout a pour but d'être réutilisé à travers les applications, nous recommandons que le layout supprime l'élément, mais le framework de la vue graphique ne dépend pas de cela.

La sous-classe est libre de décider de la façon de conserver les éléments.

Voir aussi itemAt() et count().

void QGraphicsLayout::setContentsMargins ( qreal left, qreal top, qreal right, qreal bottom )

Définit les marges de contenu à left, top, right et bottom. La marge de contenu par défaut pour le layout le plus au-dessus est dépendante du style (en s'informant du pixelMetric pour QStyle::PM_LayoutLeftMargin, QStyle::PM_LayoutTopMargin, QStyle::PM_LayoutRightMargin et QStyle::PM_LayoutBottomMargin).

Pour les sous-layouts, la marge par défaut est 0.

Le changement de la marge de contenu invalide automatiquement le layout.

Voir aussi invalidate().

void QGraphicsLayout::updateGeometry () [virtual]

Réimplémentation de QGraphicsLayoutItem::updateGeometry().

void QGraphicsLayout::widgetEvent ( QEvent * e ) [virtual]

Ce gestionnaire d'événements virtuel reçoit tous les événements pour le widget géré. QGraphicsLayout utilise ce gestionnaire d'événements pour surveiller les événements liés au layout comme les changements de géométrie, de layout ou de direction du layout.

L'argument e est un pointeur sur l'événement.

Vous pouvez réimplémenter ce gestionnaire d'événements pour surveiller les événements similaires pour votre layout personnalisé.

Voir aussi QGraphicsWidget::event() et QGraphicsItem::sceneEvent().

Remerciements

Merci à Alexandre Laurent pour la traduction ainsi qu'à Thibaut Cuvelier et Jonathan Courtois et Claude Leloup pour leur relecture !