QGraphicsLayout Class
La classe `QGraphicsLayout` sert de classe de base à toutes les dispositions de la vue graphique. En savoir plus...
| En-tête : | #include <QGraphicsLayout> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake : | QT += widgets |
| Hérite de : | QGraphicsLayoutItem |
| Hérité par : | QGraphicsAnchorLayout, QGraphicsGridLayout et QGraphicsLinearLayout |
Fonctions publiques
| QGraphicsLayout(QGraphicsLayoutItem *parent = nullptr) | |
| virtual | ~QGraphicsLayout() |
| void | activate() |
| virtual int | count() const = 0 |
| virtual void | invalidate() |
| bool | isActivated() const |
| virtual QGraphicsLayoutItem * | itemAt(int i) const = 0 |
| virtual void | removeAt(int index) = 0 |
| void | setContentsMargins(qreal left, qreal top, qreal right, qreal bottom) |
| virtual void | widgetEvent(QEvent *e) |
Fonctions publiques réimplémentées
| virtual void | getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const override |
| virtual void | updateGeometry() override |
Fonctions protégées
| void | addChildLayoutItem(QGraphicsLayoutItem *layoutItem) |
Description détaillée
QGraphicsLayout est une classe abstraite qui définit une API virtuelle permettant d’agencer les enfants d’ QGraphicsWidget s et d’autres objets d’ QGraphicsLayoutItem pour une QGraphicsWidget. QGraphicsWidget attribue la responsabilité à un QGraphicsLayout via QGraphicsWidget::setLayout(). Lorsque le widget est redimensionné, la mise en page réorganise automatiquement les enfants du widget. QGraphicsLayout hérite de QGraphicsLayoutItem, ce qui lui permet d’être géré par n’importe quelle disposition, y compris ses propres sous-classes.
Écrire une disposition personnalisée
Vous pouvez utiliser QGraphicsLayout comme base pour écrire votre propre disposition personnalisée (par exemple, une disposition en flux), mais il est plus courant d’utiliser l’une de ses sous-classes à la place : QGraphicsLinearLayout ou QGraphicsGridLayout. Lors de la création d’une disposition personnalisée, les fonctions suivantes doivent au minimum être réimplémentées :
| Fonction | Description |
|---|---|
| QGraphicsLayoutItem::setGeometry() | Vous avertit lorsque la géométrie de la mise en page est définie. Vous pouvez stocker la géométrie dans votre propre classe de mise en page en réimplémentant cette fonction. |
| QGraphicsLayoutItem::sizeHint() | Renvoie les indications de taille de la mise en page. |
| QGraphicsLayout::count() | Renvoie le nombre d'éléments dans votre mise en page. |
| QGraphicsLayout::itemAt() | Renvoie un pointeur vers un élément de votre mise en page. |
| QGraphicsLayout::removeAt() | Supprime un élément de votre mise en page sans le détruire. |
Pour plus de détails sur la manière d'implémenter chaque fonction, consultez la documentation de chaque fonction.
Chaque mise en page définit sa propre API pour l'agencement des widgets et des éléments de mise en page. Par exemple, avec une mise en page en grille, vous avez besoin d'un index de ligne et d'une colonne, avec en option des étendues de ligne et de colonne, l'alignement, l'espacement, etc. Une disposition linéaire, en revanche, nécessite un seul index de ligne ou de colonne pour positionner ses éléments. Pour une disposition en grille, l’ordre d’insertion n’affecte en rien la disposition, mais pour une disposition linéaire, cet ordre est essentiel. Lorsque vous écrivez votre propre sous-classe de disposition, vous êtes libre de choisir l’API qui convient le mieux à votre disposition.
QGraphicsLayout fournit la fonction de commodité ` addChildLayoutItem()` pour ajouter des éléments de mise en page à une mise en page personnalisée. Cette fonction réaffectera automatiquement les éléments graphiques à un parent, si nécessaire.
Activation de la mise en page
Lorsque la géométrie de la mise en page change, QGraphicsLayout réorganise immédiatement tous les éléments qu’il gère en appelant setGeometry() sur chaque élément. Cette réorganisation s’appelle l’activation de la mise en page.
QGraphicsLayout met à jour sa propre géométrie pour qu’elle corresponde à celle obtenue par ` contentsRect()` du ` QGraphicsLayoutItem ` qu’il gère. Ainsi, il réorganise automatiquement tous ses éléments lorsque le widget est redimensionné. QGraphicsLayout met en cache les tailles de tous les éléments qu’il gère afin d’éviter d’appeler trop souvent ` setGeometry()`.
Remarque : un QGraphicsLayout aura la même géométrie que l'contentsRect() du widget (et non de la mise en page) auquel il est affecté.
Activation implicite de la disposition
La mise en page peut être activée implicitement de deux façons : en appelant ` activate()` ou en appelant ` invalidate()`. L’appel de ` activate()` active immédiatement la mise en page. En revanche, l’appel de ` invalidate()` est différé, car il envoie un événement ` LayoutRequest ` au widget géré. En raison de la compression des événements, la fonction ` activate()` ne sera appelée qu’une seule fois une fois que le contrôle aura été rendu à la boucle d’événements. C’est ce qu’on appelle l’invalidation de la mise en page. L’invalidation de la mise en page invalide également toutes les informations mises en cache. Par ailleurs, la fonction invalidate() est une fonction virtuelle. Vous pouvez donc invalider votre propre cache dans une sous-classe de QGraphicsLayout en réimplémentant cette fonction.
Gestion des événements
QGraphicsLayout écoute les événements du widget qu’il gère via le gestionnaire d’événements virtuel widgetEvent(). Lorsqu’une mise en page est attribuée à un widget, tous les événements transmis au widget sont d’abord traités par widgetEvent(). Cela permet à la mise en page d’être informée de tout changement d’état pertinent sur le widget, tel que les changements de visibilité ou de sens de mise en page.
Gestion des marges
Les marges d’un QGraphicsLayout peuvent être modifiées en réimplémentant les méthodes setContentsMargins() et getContentsMargins().
Documentation des fonctions membres
QGraphicsLayout::QGraphicsLayout(QGraphicsLayoutItem *parent = nullptr)
Crée un objet QGraphicsLayout.
parent est transmis au constructeur d'QGraphicsLayoutItem et l'argument isLayout d'QGraphicsLayoutItem est défini sur true.
Si ` parent ` est un ` QGraphicsWidget `, la mise en page sera installée sur ce widget. (Notez que l'installation d'une mise en page supprimera l'ancienne mise en page installée.)
[virtual noexcept] QGraphicsLayout::~QGraphicsLayout()
Supprime l'objet ` QGraphicsLayout `.
void QGraphicsLayout::activate()
Active la mise en page, ce qui entraîne le réagencement immédiat de tous les éléments qu'elle contient. Cette fonction repose sur l'appel des méthodes ` count()` et ` itemAt()`, puis sur l'appel séquentiel de la méthode ` setGeometry()` pour tous les éléments. Une fois activée, la mise en page ajustera sa géométrie en fonction de la méthode ` contentsRect()` de son élément parent. Ce dernier invalidera alors toute mise en page qui lui est propre.
Si elle est appelée de manière séquentielle ou récursive, par exemple par l’un des éléments disposés en réponse à un redimensionnement, cette fonction n’aura aucun effet.
Notez que la disposition est libre d’utiliser la mise en cache de la géométrie pour optimiser ce processus. Pour invalider de force ce cache, vous pouvez appeler ` invalidate()` avant d’appeler `activate()`.
Voir également invalidate().
[protected] void QGraphicsLayout::addChildLayoutItem(QGraphicsLayoutItem *layoutItem)
Cette fonction est une fonction pratique destinée aux mises en page personnalisées ; elle parcourt tous les éléments de la mise en page et réaffecte leurs éléments graphiques à l’ancêtre QGraphicsWidget le plus proche de la mise en page.
Si « layoutItem » se trouve déjà dans une autre mise en page, il en sera supprimé.
Si les mises en page personnalisées souhaitent un comportement particulier, elles peuvent ignorer cette fonction et implémenter leur propre comportement.
Voir également graphicsItem().
[pure virtual] int QGraphicsLayout::count() const
Cette fonction purement virtuelle doit être réimplémentée dans une sous-classe de ` QGraphicsLayout ` afin de renvoyer le nombre d'éléments contenus dans la disposition.
La sous-classe est libre de choisir la manière de stocker les éléments.
Voir également ` itemAt()` et ` removeAt()`.
[override virtual] void QGraphicsLayout::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const
Réimplémentation de : QGraphicsLayoutItem::getContentsMargins(qreal *left, qreal *top, qreal *right, qreal *bottom) const.
[virtual] void QGraphicsLayout::invalidate()
Efface toutes les informations mises en cache concernant la géométrie et les indications de taille dans la mise en page, puis déclenche un événement « LayoutRequest » sur l'QGraphicsLayoutItem parent géré.
Voir également activate() et setGeometry().
bool QGraphicsLayout::isActivated() const
Renvoie « true » si la mise en page est en cours d’activation ; sinon, renvoie « false ». Si la mise en page est en cours d’activation, cela signifie qu’elle est actuellement en train de réorganiser ses éléments (c’est-à-dire que la fonction activate() a été appelée et n’a pas encore renvoyé de résultat).
Voir également activate() et invalidate().
[pure virtual] QGraphicsLayoutItem *QGraphicsLayout::itemAt(int i) const
Cette fonction purement virtuelle doit être réimplémentée dans une sous-classe de ` QGraphicsLayout ` afin de renvoyer un pointeur vers l'élément situé à l'index ` i`. La réimplémentation peut supposer que ` i ` est valide (c'est-à-dire qu'elle respecte la valeur de ` count()`). Associée à ` count()`, elle permet de parcourir tous les éléments d'une disposition.
La sous-classe est libre de décider comment stocker les éléments, et la disposition visuelle ne doit pas nécessairement être reflétée par cette fonction.
Voir également count() et removeAt().
[pure virtual] void QGraphicsLayout::removeAt(int index)
Cette fonction purement virtuelle doit être réimplémentée dans une sous-classe de ` QGraphicsLayout ` afin de supprimer l'élément situé à l'adresse ` index`. La réimplémentation peut supposer que ` index ` est valide (c'est-à-dire qu'elle respecte la valeur de ` count()`).
L’implémentation doit garantir que la méthode ` parentLayoutItem()` de l’élément supprimé ne pointe pas vers cette mise en page, puisque l’élément est considéré comme ayant été retiré de la hiérarchie de mise en page.
Si la mise en page doit être réutilisée entre différentes applications, nous recommandons que la mise en page supprime l’élément, mais le framework de vue graphique ne dépend pas de cette opération.
La sous-classe est libre de décider comment stocker les éléments.
Voir également itemAt() et count().
void QGraphicsLayout::setContentsMargins(qreal left, qreal top, qreal right, qreal bottom)
Définit les marges de contenu sur left, top, right et bottom. Les marges de contenu par défaut pour les mises en page de niveau supérieur dépendent du style (en interrogeant la propriété pixelMetric pour obtenir les valeurs QStyle::PM_LayoutLeftMargin, QStyle::PM_LayoutTopMargin, QStyle::PM_LayoutRightMargin et QStyle::PM_LayoutBottomMargin).
Pour les sous-mises en page, les marges par défaut sont de 0.
La modification des marges de contenu invalide automatiquement la mise en page.
Voir également invalidate().
[override virtual] void QGraphicsLayout::updateGeometry()
Réimplémente : QGraphicsLayoutItem::updateGeometry().
[virtual] void QGraphicsLayout::widgetEvent(QEvent *e)
Ce gestionnaire d'événements virtuel reçoit tous les événements liés au widget géré. La méthode ` QGraphicsLayout ` utilise ce gestionnaire d'événements pour détecter les événements liés à la mise en page, tels que les modifications de géométrie, les changements de mise en page ou les changements de direction de mise en page.
e est un pointeur vers l'événement.
Vous pouvez réimplémenter ce gestionnaire d'événements pour suivre des événements similaires pour votre propre mise en page personnalisée.
Voir également ` QGraphicsWidget::event()` et ` QGraphicsItem::sceneEvent()`.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
