이 페이지에서

QBoxLayout Class

QBoxLayout 클래스는 자식 위젯을 가로 또는 세로로 정렬합니다. 더 보기...

헤더: #include <QBoxLayout>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
상속: QLayout
상속받는 항목:

QHBoxLayout 그리고 QVBoxLayout

공개 유형

enum Direction { LeftToRight, RightToLeft, TopToBottom, BottomToTop }

공개 함수

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

재구현된 공용 함수

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

상세 설명

QBoxLayout은 (부모 레이아웃이나 parentWidget()에서) 할당받은 공간을 받아 이를 상자 행으로 나누고, 관리되는 각 위젯이 하나의 상자를 채우도록 합니다.

가로로 배열된 5개의 버튼

QBoxLayout의 방향이 Qt::Horizontal 인 경우, 박스들은 적절한 크기로 한 줄에 배치됩니다. 각 위젯(또는 다른 박스)은 최소한 최소 크기를, 최대 최대 크기를 할당받습니다. 남은 공간은 스트레치 계수(자세한 내용은 아래 참조)에 따라 분배됩니다.

세로로 배열된 5개의 버튼

QBoxLayout의 방향이 ` Qt::Vertical`인 경우, 상자들은 적절한 크기로 열(column) 형태로 배치됩니다.

QBoxLayout을 생성하는 가장 쉬운 방법은 편의 클래스 중 하나를 사용하는 것입니다. 예를 들어, QHBoxLayout ( Qt::Horizontal 상자용)이나 QVBoxLayout ( Qt::Vertical 상자용)이 있습니다. 또한 QBoxLayout 생성자를 직접 사용하여 방향을 LeftToRight, RightToLeft, TopToBottom 또는 BottomToTop 로 지정할 수도 있습니다.

QBoxLayout이 최상위 레이아웃이 아닌 경우(즉, 위젯의 전체 영역과 자식 요소를 모두 관리하지 않는 경우), 이를 사용하여 작업을 수행하기 전에 부모 레이아웃에 추가해야 합니다. 레이아웃을 추가하는 일반적인 방법은 parentLayout->addLayout()를 호출하는 것입니다.

이 작업을 완료하면 다음 네 가지 함수 중 하나를 사용하여 QBoxLayout에 박스를 추가할 수 있습니다:

  • addWidget()를 사용하여 QBoxLayout에 위젯을 추가하고 위젯의 스트레치 계수를 설정합니다. (스트레치 계수는 박스 행을 따라 적용됩니다.)
  • addSpacing()는 빈 박스를 생성합니다. 이 함수는 깔끔하고 널찍한 대화 상자를 만드는 데 사용하는 함수 중 하나입니다. 여백을 설정하는 방법은 아래를 참조하십시오.
  • addStretch()는 비어 있고 확장 가능한 박스를 생성합니다.
  • addLayout()는 다른 QLayout 를 포함하는 박스를 행에 추가하고 해당 레이아웃의 신축 계수를 설정합니다.

insertWidget(), insertSpacing(), insertStretch() 또는 insertLayout()을 사용하여 레이아웃의 지정된 위치에 상자를 삽입합니다.

QBoxLayout에는 두 가지 여백 너비가 포함되어 있습니다:

  • setContentsMargins()는 위젯의 각 측면에 있는 바깥쪽 테두리의 너비를 설정합니다. 이는 QBoxLayout의 네 측면 각각을 따라 예약된 공간의 너비입니다.
  • setSpacing()는 인접한 박스들 사이의 너비를 설정합니다. ( addSpacing()을 사용하여 특정 위치에 더 많은 공간을 확보할 수 있습니다.)

여백의 기본값은 스타일에 의해 제공됩니다. 대부분의 Qt 스타일이 지정하는 기본 여백은 자식 위젯의 경우 9, 창의 경우 11입니다. 간격의 기본값은 최상위 레이아웃의 여백 너비와 같거나, 상위 레이아웃의 여백 너비와 같습니다.

레이아웃에서 위젯을 제거하려면 ` removeWidget()`를 호출하십시오. 위젯에 대해 ` QWidget::hide()`를 호출하면 ` QWidget::show()`가 호출될 때까지 해당 위젯이 레이아웃에서 사실상 제거됩니다.

편리한 생성자 기능 덕분에 거의 항상 QBoxLayout보다는 QVBoxLayout 와 QHBoxLayout 를 사용하는 것이 좋습니다.

QGridLayout, QStackedLayout 및 레이아웃 관리항목도 참조하십시오 .

멤버 유형 문서

enum QBoxLayout::Direction

이 유형은 상자 레이아웃의 방향을 결정하는 데 사용됩니다.

상수값설명
QBoxLayout::LeftToRight0왼쪽에서 오른쪽으로 가로 방향.
QBoxLayout::RightToLeft1오른쪽에서 왼쪽으로 가로 방향.
QBoxLayout::TopToBottom2위에서 아래로 수직.
QBoxLayout::BottomToTop3아래에서 위로 수직.

멤버 함수 문서

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

dir 방향과 parent 부모 위젯을 가진 새로운 QBoxLayout을 생성합니다.

이 레이아웃은 parent 의 최상위 레이아웃으로 직접 설정됩니다. 위젯당 최상위 레이아웃은 하나만 있을 수 있습니다. 이 레이아웃은 QWidget::layout()에 의해 반환됩니다.

direction() 및 QWidget::setLayout()도 참조하십시오 .

[virtual noexcept] QBoxLayout::~QBoxLayout()

이 박스 레이아웃을 제거합니다.

레이아웃의 위젯은 제거되지 않습니다.

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

QLayout::addItem(QLayoutItem *item)을 재구현합니다.

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

박스 끝부분에 ` layout `를 추가하며, 직렬 신장 계수는 ` stretch`입니다.

layout box 레이아웃의 자식 요소가 됩니다.

insertLayout(), addItem() 및 addWidget()도 참조하십시오 .

void QBoxLayout::addSpacerItem(QSpacerItem *spacerItem)

이 박스 레이아웃의 끝에 ` spacerItem `를 추가합니다.

spacerItem 의 소유권이 이 레이아웃으로 전달됩니다.

addSpacing() 및 addStretch()도 참조하십시오 .

void QBoxLayout::addSpacing(int size)

이 박스 레이아웃의 끝에 크기 size 인 비확장 가능 공간( QSpacerItem)을 추가합니다. QBoxLayout 는 기본 여백과 간격을 제공합니다. 이 함수는 추가 공간을 삽입합니다.

insertSpacing(), addItem() 및 QSpacerItem도 참조하십시오 .

void QBoxLayout::addStretch(int stretch = 0)

이 박스 레이아웃의 끝에 최소 크기가 0이고 신축 계수 stretch 인 신축 가능한 공간( QSpacerItem)을 추가합니다.

insertStretch(), addItem() 및 QSpacerItem도 참조하십시오 .

void QBoxLayout::addStrut(int size)

상자의 수직 치수(예: 상자가 LeftToRight 인 경우 높이)를 최소 size 로 제한합니다. 다른 제약 조건에 따라 이 제한치가 증가할 수 있습니다.

addItem()도 참조하십시오 .

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

이 상자 레이아웃의 끝에 widget 를 추가하며, 스트레치 계수는 stretch 이고 정렬은 alignment 입니다.

신축 계수는 QBoxLayout 의 direction 에서만 적용되며, 이 QBoxLayout 내의 다른 박스 및 위젯을 기준으로 합니다. 신축 계수가 더 높은 위젯과 박스는 더 크게 확장됩니다.

stretchFactor가 0이고 QBoxLayout 내의 다른 요소 중 stretchFactor가 0보다 큰 요소가 없는 경우, 공간은 관련된 각 위젯의 QWidget::sizePolicy()에 따라 분배됩니다.

정렬 방식은 alignment 로 지정됩니다. 기본 정렬 값은 0이며, 이는 위젯이 셀 전체를 채운다는 것을 의미합니다.

widget QLayout::parentWidget()의 자식 요소가 됩니다.

insertWidget(), addItem(), addLayout(), addStretch(), addSpacing(), addStrut()도 참조하십시오 .

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

QLayout::count() const를 재구현합니다.

QBoxLayout::Direction QBoxLayout::direction() const

상자의 방향을 반환합니다. ` addWidget()` 및 ` addSpacing()`는 이 방향으로 작동하며, `stretch`는 이 방향으로 확장됩니다.

setDirection(), QBoxLayout::Direction, addWidget(), addSpacing()도 참조하십시오 .

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

QLayout::expandingDirections() const를 재구현합니다.

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

QLayoutItem::hasHeightForWidth() const를 재구현합니다.

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

QLayoutItem::heightForWidth(int) const를 재구현합니다.

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

이 박스 레이아웃의 index 위치에 item 를 삽입합니다. 인덱스는 음수이거나 0부터 count() 사이의 값이어야 하며, 이 범위에는 해당 값도 포함됩니다. index 가 음수이거나 count()인 경우, 해당 항목은 끝에 추가됩니다.

item 의 소유권은 이 레이아웃으로 전달됩니다.

addItem(), insertWidget(), insertLayout(), insertStretch(), insertSpacing()도 참조하십시오 .

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

index 위치에 layout 를 삽입하며, 스트레치 계수는 stretch 입니다. index 가 음수인 경우, 레이아웃은 맨 끝에 추가됩니다.

layout box 레이아웃의 자식 요소가 됩니다.

addLayout() 및 insertItem()도 참조하십시오 .

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

index 위치에 spacerItem 를 삽입하며, 최소 크기와 신축 계수는 0으로 설정합니다. index 가 음수인 경우, 공백은 끝부분에 추가됩니다.

spacerItem 의 소유권은 이 레이아웃으로 전달됩니다.

addSpacerItem(), insertStretch(), insertSpacing()도 참조하십시오 .

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

index 위치에 크기 size 인 비확장 공백( QSpacerItem)을 삽입합니다. index 가 음수인 경우 공백은 끝부분에 추가됩니다.

박스 레이아웃에는 기본 여백과 간격이 설정되어 있습니다. 이 함수는 추가적인 공간을 삽입합니다.

addSpacing(), insertItem(), QSpacerItem도 참조하십시오 .

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

index 위치에 최소 크기가 0이고 신축 계수가 stretch 인 신축 가능한 공백( QSpacerItem)을 삽입합니다. index 가 음수인 경우, 공백은 문장의 끝에 추가됩니다.

addStretch(), insertItem(), QSpacerItem도 참조하십시오 .

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

위치 index 에 widget 를 삽입하며, 확장 계수 stretch 및 정렬 alignment 을 적용합니다. index 가 음수인 경우, 위젯은 끝에 추가됩니다.

신축 계수는 QBoxLayout 의 direction 내에서만 적용되며, 이 QBoxLayout 내의 다른 박스 및 위젯을 기준으로 합니다. 신축 계수가 더 높은 위젯과 박스는 더 크게 확장됩니다.

stretch factor가 0이고 QBoxLayout 내의 다른 어떤 요소도 stretch factor가 0보다 크지 않은 경우, 공간은 관련된 각 위젯의 QWidget::sizePolicy()에 따라 분배됩니다.

정렬은 alignment 로 지정됩니다. 기본 정렬 값은 0이며, 이는 위젯이 셀 전체를 채운다는 것을 의미합니다.

widget QLayout::parentWidget()의 자식 요소가 됩니다.

addWidget() 및 insertItem()도 참조하십시오 .

[override virtual] void QBoxLayout::invalidate()

QLayout::invalidate()를 재구현합니다.

캐시된 정보를 초기화합니다.

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

QLayout::itemAt(int index) const를 재구현합니다.

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

QLayout::maximumSize() const를 재구현합니다.

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

QLayoutItem::minimumHeightForWidth(int w) const를 재구현합니다.

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

QLayout::minimumSize() const를 재구현합니다.

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

이 레이아웃의 방향을 direction 로 설정합니다.

direction()도 참조하십시오 .

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

QLayout::setGeometry(const QRect &r)를 재구현합니다.

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

QLayout::spacing 속성에 대한 액세스 함수를 재구현합니다.

QLayout::setSpacing()를 재구현합니다. spacing 속성을 spacing 로 설정합니다.

QLayout::setSpacing() 및 spacing()도 참조하십시오 .

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

index 위치의 신축 계수를 stretch 로 설정합니다.

stretch()도 참조하십시오 .

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

widget 의 스트레치 계수를 stretch 로 설정하고, 이 레이아웃(자식 레이아웃 제외)에서 widget 가 발견되면 true를 반환하며, 그렇지 않으면 false 를 반환합니다.

setAlignment()도 참조하십시오 .

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

레이아웃 layout 의 신축 계수를 stretch 로 설정하고, 이 레이아웃(자식 레이아웃 제외)에서 layout 가 발견되면 true 를 반환하며, 그렇지 않으면 false 를 반환합니다.

이 함수는 오버로드된 함수입니다.

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

QLayoutItem::sizeHint() const를 재구현합니다.

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

QLayout::spacing 속성에 대한 액세스 함수를 재구현합니다.

QLayout::spacing()를 재구현합니다. spacing 속성이 유효한 경우, 해당 값을 반환합니다. 그렇지 않은 경우, spacing 속성의 값을 계산하여 반환합니다. 위젯 내 레이아웃 간격은 스타일에 따라 달라지므로, 부모가 위젯인 경우 스타일에서 레이아웃의 (수평 또는 수직) 간격을 조회합니다. 그렇지 않은 경우, 부모가 레이아웃이므로 상위 레이아웃에서 spacing()을 조회합니다.

QLayout::spacing() 및 setSpacing()도 참조하십시오 .

int QBoxLayout::stretch(int index) const

index 위치의 신축 계수를 반환합니다.

setStretch()도 참조하십시오 .

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

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.