Sur cette page

QBoxLayout Class

La classe QBoxLayout aligne les widgets enfants horizontalement ou verticalement. Plus d'informations...

En-tête : #include <QBoxLayout>
CMake : find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake : QT += widgets
Hérite : QLayout
Héritée par :

QHBoxLayout et QVBoxLayout

Types publics

enum Direction { LeftToRight, RightToLeft, TopToBottom, BottomToTop }

Fonctions publiques

QBoxLayout(QBoxLayout::Direction dir, QWidget *parent = nullptr)
virtual ~QBoxLayout()
void addLayout(QLayout *layout, int stretch = 0)
void addSpacerItem(QSpacerItem *spacerItem)
void addSpacing(int size)
void addStretch(int stretch = 0)
void addStrut(int size)
void addWidget(QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())
QBoxLayout::Direction direction() const
void insertItem(int index, QLayoutItem *item)
void insertLayout(int index, QLayout *layout, int stretch = 0)
void insertSpacerItem(int index, QSpacerItem *spacerItem)
void insertSpacing(int index, int size)
void insertStretch(int index, int stretch = 0)
void insertWidget(int index, QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())
void setDirection(QBoxLayout::Direction direction)
void setStretch(int index, int stretch)
bool setStretchFactor(QWidget *widget, int stretch)
bool setStretchFactor(QLayout *layout, int stretch)
int stretch(int index) const

Fonctions publiques réimplémentées

virtual void addItem(QLayoutItem *item) override
virtual int count() const override
virtual Qt::Orientations expandingDirections() const override
virtual bool hasHeightForWidth() const override
virtual int heightForWidth(int w) const override
virtual void invalidate() override
virtual QLayoutItem *itemAt(int index) const override
virtual QSize maximumSize() const override
virtual int minimumHeightForWidth(int w) const override
virtual QSize minimumSize() const override
virtual void setGeometry(const QRect &r) override
virtual void setSpacing(int spacing) override
virtual QSize sizeHint() const override
virtual int spacing() const override
virtual QLayoutItem *takeAt(int index) override

Description détaillée

QBoxLayout prend l'espace qu'il reçoit (de son layout parent ou de parentWidget()), le divise en une rangée de boîtes et fait en sorte que chaque widget géré remplisse une boîte.

Cinq boutons en disposition horizontale

Si l'orientation du QBoxLayout est Qt::Horizontal, les boîtes sont placées dans une rangée, avec des tailles appropriées. Chaque widget (ou autre boîte) aura au moins sa taille minimale et au plus sa taille maximale. Tout espace excédentaire est partagé en fonction des facteurs d'étirement (voir ci-dessous).

Cinq boutons en disposition verticale

Si l'orientation du QBoxLayout est Qt::Vertical, les boîtes sont placées dans une colonne, toujours avec des tailles appropriées.

La manière la plus simple de créer un QBoxLayout est d'utiliser l'une des classes de commodité, par exemple QHBoxLayout (pour les boîtes Qt::Horizontal ) ou QVBoxLayout (pour les boîtes Qt::Vertical ). Vous pouvez également utiliser le constructeur QBoxLayout directement, en spécifiant sa direction comme LeftToRight, RightToLeft, TopToBottom, ou BottomToTop.

Si le QBoxLayout n'est pas la disposition de premier niveau (c'est-à-dire qu'il ne gère pas l'ensemble de la zone et des enfants du widget), vous devez l'ajouter à sa disposition parentale avant de pouvoir faire quoi que ce soit avec lui. La manière normale d'ajouter une disposition est d'appeler parentLayout->addLayout().

Une fois cette opération effectuée, vous pouvez ajouter des boîtes au QBoxLayout à l'aide de l'une des quatre fonctions suivantes :

  • addWidget() pour ajouter un widget au QBoxLayout et définir le facteur d'étirement du widget. (Le facteur d'étirement se situe le long de la rangée de boîtes).
  • addSpacing() pour créer une boîte vide ; c'est l'une des fonctions que vous utilisez pour créer de belles boîtes de dialogue spacieuses. Voir ci-dessous les méthodes de définition des marges.
  • addStretch() pour créer une boîte vide et extensible.
  • addLayout() pour ajouter une boîte contenant une autre QLayout à la ligne et définir le facteur d'étirement de cette disposition.

Utilisez insertWidget(), insertSpacing(), insertStretch() ou insertLayout() pour insérer une boîte à une position spécifiée dans la mise en page.

QBoxLayout comprend également deux largeurs de marge :

  • setContentsMargins() définit la largeur de la bordure extérieure de chaque côté du widget. Il s'agit de la largeur de l'espace réservé le long de chacun des quatre côtés de QBoxLayout.
  • setSpacing() définit la largeur entre les boîtes voisines. (Vous pouvez utiliser addSpacing() pour obtenir plus d'espace à un endroit particulier).

La marge par défaut est fournie par le style. La marge par défaut spécifiée par la plupart des styles Qt Widgets est de 9 pour les widgets enfants et de 11 pour les fenêtres. Par défaut, l'espacement est identique à la largeur de la marge d'une disposition de niveau supérieur ou à celle de la disposition parentale.

Pour supprimer un widget d'une disposition, appelez removeWidget(). L'appel à QWidget::hide() sur un widget supprime également le widget de la mise en page jusqu'à ce que QWidget::show() soit appelé.

Vous souhaiterez presque toujours utiliser QVBoxLayout et QHBoxLayout plutôt que QBoxLayout en raison de leurs constructeurs pratiques.

Voir également QGridLayout, QStackedLayout, et Layout Management.

Documentation sur les types de membres

enum QBoxLayout::Direction

Ce type est utilisé pour déterminer la direction de la disposition d'une boîte.

ConstanteValeurDescription
QBoxLayout::LeftToRight0Horizontal de gauche à droite.
QBoxLayout::RightToLeft1Horizontal de la droite vers la gauche.
QBoxLayout::TopToBottom2Verticale de haut en bas.
QBoxLayout::BottomToTop3Vertical de bas en haut.

Documentation des fonctions membres

[explicit] QBoxLayout::QBoxLayout(QBoxLayout::Direction dir, QWidget *parent = nullptr)

Construit un nouveau QBoxLayout avec la direction dir et le widget parent parent.

Le layout est directement défini comme layout de premier niveau pour parent. Il ne peut y avoir qu'une seule présentation de premier niveau pour un widget. Elle est renvoyée par QWidget::layout().

Voir aussi direction() et QWidget::setLayout().

[virtual noexcept] QBoxLayout::~QBoxLayout()

Détruit cette boîte de présentation.

Les widgets de la disposition ne sont pas détruits.

[override virtual] void QBoxLayout::addItem(QLayoutItem *item)

Réimplémente : QLayout::addItem(QLayoutItem *item).

void QBoxLayout::addLayout(QLayout *layout, int stretch = 0)

Ajoute layout à la fin de la boîte, avec le facteur d'étirement en série stretch.

layout devient un enfant de la disposition de la boîte.

Voir aussi insertLayout(), addItem() et addWidget().

void QBoxLayout::addSpacerItem(QSpacerItem *spacerItem)

Ajoute spacerItem à la fin de ce modèle de boîte.

La propriété de spacerItem est transmise à cette disposition.

Voir aussi addSpacing() et addStretch().

void QBoxLayout::addSpacing(int size)

Ajoute un espace non extensible (un QSpacerItem) de taille size à la fin de cette mise en page. QBoxLayout fournit une marge et un espacement par défaut. Cette fonction ajoute un espace supplémentaire.

Voir également insertSpacing(), addItem() et QSpacerItem.

void QBoxLayout::addStretch(int stretch = 0)

Ajoute un espace étirable ( QSpacerItem) de taille minimale nulle et de facteur d'étirement stretch à la fin de cette disposition en boîte.

Voir également insertStretch(), addItem() et QSpacerItem.

void QBoxLayout::addStrut(int size)

Limite la dimension perpendiculaire de la boîte (par exemple la hauteur si la boîte est LeftToRight) à un minimum de size. D'autres contraintes peuvent augmenter la limite.

Voir également addItem().

void QBoxLayout::addWidget(QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())

Ajoute widget à la fin de cette disposition de boîte, avec un facteur d'étirement de stretch et un alignement de alignment.

Le facteur d'étirement ne s'applique qu'au direction du QBoxLayout, et est relatif aux autres boîtes et widgets de ce QBoxLayout. Les widgets et les boîtes dont le facteur d'étirement est plus élevé grandissent davantage.

Si le facteur d'étirement est de 0 et que rien d'autre dans le QBoxLayout n'a un facteur d'étirement supérieur à zéro, l'espace est distribué en fonction de QWidget::sizePolicy() de chaque widget concerné.

L'alignement est spécifié par alignment. L'alignement par défaut est 0, ce qui signifie que le widget remplit toute la cellule.

widget devient un enfant de QLayout::parentWidget().

Voir aussi insertWidget(), addItem(), addLayout(), addStretch(), addSpacing() et addStrut().

[override virtual] int QBoxLayout::count() const

Réimplémente : QLayout::count() const.

QBoxLayout::Direction QBoxLayout::direction() const

Renvoie la direction de la boîte. addWidget() et addSpacing() fonctionnent dans cette direction ; l'étirement s'étend dans cette direction.

Voir aussi setDirection(), QBoxLayout::Direction, addWidget() et addSpacing().

[override virtual] Qt::Orientations QBoxLayout::expandingDirections() const

Réimplémente : QLayout::expandingDirections() const.

[override virtual] bool QBoxLayout::hasHeightForWidth() const

Réimplémente : QLayoutItem::hasHeightForWidth() const.

[override virtual] int QBoxLayout::heightForWidth(int w) const

Réimplémente : QLayoutItem::heightForWidth(int) const.

void QBoxLayout::insertItem(int index, QLayoutItem *item)

Insère item dans ce modèle de boîte à la position index. L'indice doit être négatif ou compris entre 0 et count(), inclusivement. Si index est négatif ou count(), l'élément est ajouté à la fin.

La propriété de item est transmise à cette disposition.

Voir également addItem(), insertWidget(), insertLayout(), insertStretch() et insertSpacing().

void QBoxLayout::insertLayout(int index, QLayout *layout, int stretch = 0)

Insère layout à la position index, avec le facteur d'étirement stretch. Si index est négatif, la disposition est ajoutée à la fin.

layout devient un enfant de la disposition de la boîte.

Voir également addLayout() et insertItem().

void QBoxLayout::insertSpacerItem(int index, QSpacerItem *spacerItem)

Insère spacerItem à la position index, avec une taille minimale et un facteur d'étirement nuls. Si index est négatif, l'espace est ajouté à la fin.

La propriété de spacerItem est transmise à cette disposition.

Voir aussi addSpacerItem(), insertStretch() et insertSpacing().

void QBoxLayout::insertSpacing(int index, int size)

Insère un espace non extensible (un QSpacerItem) à la position index, de taille size. Si index est négatif, l'espace est ajouté à la fin.

La mise en page de la boîte a une marge et un espacement par défaut. Cette fonction ajoute un espace supplémentaire.

Voir également addSpacing(), insertItem() et QSpacerItem.

void QBoxLayout::insertStretch(int index, int stretch = 0)

Insère un espace étirable (a QSpacerItem) à la position index, avec une taille minimale nulle et un facteur d'étirement stretch. Si index est négatif, l'espace est ajouté à la fin.

Voir également addStretch(), insertItem() et QSpacerItem.

void QBoxLayout::insertWidget(int index, QWidget *widget, int stretch = 0, Qt::Alignment alignment = Qt::Alignment())

Insère widget à la position index, avec le facteur d'étirement stretch et l'alignement alignment. Si index est négatif, le widget est ajouté à la fin.

Le facteur d'étirement ne s'applique qu'à direction du site QBoxLayout et est relatif aux autres boîtes et widgets de ce site QBoxLayout. Les widgets et les boîtes dont le facteur d'étirement est plus élevé grandissent davantage.

Si le facteur d'étirement est de 0 et que rien d'autre dans le QBoxLayout n'a un facteur d'étirement supérieur à zéro, l'espace est distribué en fonction du QWidget::sizePolicy() de chaque widget concerné.

L'alignement est spécifié par alignment. L'alignement par défaut est 0, ce qui signifie que le widget remplit toute la cellule.

widget devient un enfant de QLayout::parentWidget().

Voir également addWidget() et insertItem().

[override virtual] void QBoxLayout::invalidate()

Réimplémente : QLayout::invalidate().

Réinitialise les informations mises en cache.

[override virtual] QLayoutItem *QBoxLayout::itemAt(int index) const

Réimplémente : QLayout::itemAt(int index) const.

[override virtual] QSize QBoxLayout::maximumSize() const

Réimplémente : QLayout::maximumSize() const.

[override virtual] int QBoxLayout::minimumHeightForWidth(int w) const

Réimplémente : QLayoutItem::minimumHeightForWidth(int w) const.

[override virtual] QSize QBoxLayout::minimumSize() const

Réimplémente : QLayout::minimumSize() const.

void QBoxLayout::setDirection(QBoxLayout::Direction direction)

Définit la direction de cette mise en page à direction.

Voir aussi direction().

[override virtual] void QBoxLayout::setGeometry(const QRect &r)

Réimplémente : QLayout::setGeometry(const QRect &r).

[override virtual] void QBoxLayout::setSpacing(int spacing)

Réimplémente une fonction d'accès à la propriété : QLayout::spacing.

Réimplémente QLayout::setSpacing(). Définit la propriété spacing à spacing.

Voir aussi QLayout::setSpacing() et spacing().

void QBoxLayout::setStretch(int index, int stretch)

Définit le facteur d'étirement à la position index. à stretch.

Voir aussi stretch().

bool QBoxLayout::setStretchFactor(QWidget *widget, int stretch)

Fixe le facteur d'étirement de widget à stretch et renvoie vrai si widget se trouve dans cette mise en page (à l'exclusion des mises en page enfant) ; sinon, renvoie false.

Voir aussi setAlignment().

bool QBoxLayout::setStretchFactor(QLayout *layout, int stretch)

Définit le facteur d'étirement pour la mise en page layout à stretch et renvoie true si layout se trouve dans cette mise en page (à l'exclusion des mises en page enfant) ; sinon, renvoie false.

Il s'agit d'une fonction surchargée.

[override virtual] QSize QBoxLayout::sizeHint() const

Réimplémente : QLayoutItem::sizeHint() const.

[override virtual] int QBoxLayout::spacing() const

Réimplémente une fonction d'accès à la propriété : QLayout::spacing.

Réimplémente QLayout::spacing(). Si la propriété spacing est valide, cette valeur est renvoyée. Sinon, une valeur pour la propriété spacing est calculée et renvoyée. Étant donné que l'espacement de la disposition dans un widget dépend du style, si le parent est un widget, il interroge le style pour l'espacement (horizontal ou vertical) de la disposition. Dans le cas contraire, le parent est une disposition et la requête porte sur la disposition parent pour l'espacement().

Voir aussi QLayout::spacing() et setSpacing().

int QBoxLayout::stretch(int index) const

Renvoie le facteur d'étirement à la position index.

Voir aussi setStretch().

[override virtual] QLayoutItem *QBoxLayout::takeAt(int index)

Réimplémente : QLayout::takeAt(int index).

© 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.