QScrollArea Class
QScrollArea 클래스는 다른 위젯을 스크롤 가능한 뷰로 표시해 줍니다. 더 보기...
| 헤더: | #include <QScrollArea> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 상속: | QAbstractScrollArea |
속성
- alignment : Qt::Alignment
- widgetResizable : bool
공개 함수
| QScrollArea(QWidget *parent = nullptr) | |
| virtual | ~QScrollArea() |
| Qt::Alignment | alignment() const |
| void | ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50) |
| void | ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50) |
| void | setAlignment(Qt::Alignment) |
| void | setWidget(QWidget *widget) |
| void | setWidgetResizable(bool resizable) |
| QWidget * | takeWidget() |
| QWidget * | widget() const |
| bool | widgetResizable() const |
재구현된 공용 함수
| virtual bool | focusNextPrevChild(bool next) override |
| virtual QSize | sizeHint() const override |
재구현된 보호 함수
| virtual bool | event(QEvent *e) override |
| virtual bool | eventFilter(QObject *o, QEvent *e) override |
| virtual void | resizeEvent(QResizeEvent *) override |
| virtual void | scrollContentsBy(int dx, int dy) override |
| virtual QSize | viewportSizeHint() const override |
상세 설명
스크롤 영역은 프레임 내에서 자식 위젯의 내용을 표시하는 데 사용됩니다. 위젯이 프레임의 크기를 초과하는 경우, 뷰는 자식 위젯의 전체 영역을 볼 수 있도록 스크롤 막대를 제공할 수 있습니다. 자식 위젯은 ` setWidget()`로 지정해야 합니다. 예를 들어:
QLabel *imageLabel = new QLabel;
QImage image("happyguy.png");
imageLabel->setPixmap(QPixmap::fromImage(image));
scrollArea = new QScrollArea;
scrollArea->setBackgroundRole(QPalette::Dark);
scrollArea->setWidget(imageLabel);위의 코드는 이미지 레이블을 포함하는 스크롤 영역(아래 이미지에 표시됨)을 생성합니다. 이미지를 확대/축소할 때, 스크롤 영역은 필요한 스크롤 막대를 제공할 수 있습니다:
![]() | ![]() | ![]() |
스크롤 막대의 모양은 현재 설정된 ` scroll bar policies`에 따라 달라집니다. ` QAbstractScrollArea`에서 상속된 기능을 사용하여 스크롤 막대의 모양을 제어할 수 있습니다.
예를 들어, QAbstractScrollArea::horizontalScrollBarPolicy 및 QAbstractScrollArea::verticalScrollBarPolicy 속성을 설정할 수 있습니다. 또는 스크롤 영역의 내용이 변경될 때 스크롤 막대가 동적으로 조정되도록 하려면, horizontalScrollBar() 및 verticalScrollBar() 함수(스크롤 막대에 접근할 수 있게 해주는 함수)를 사용하고, QScrollBar::setValue() 함수를 통해 스크롤 영역의 내용이 변경될 때마다 스크롤 막대의 값을 설정할 수 있습니다.
widget() 함수를 사용하여 자식 위젯을 가져올 수 있습니다. setWidgetResizable() 함수를 사용하면 뷰의 크기를 조정할 수 있게 할 수 있습니다. setAlignment()을 사용하여 위젯의 정렬을 지정할 수 있습니다.
ensureVisible() 및 ensureWidgetVisible()라는 두 가지 편의 함수는 필요한 경우 콘텐츠를 스크롤하여 뷰포트 내에서 콘텐츠의 특정 영역이 보이도록 보장합니다.
크기 힌트 및 레이아웃
스크롤 영역을 사용하여 사용자 정의 위젯의 내용을 표시할 때는 자식 위젯의 ` size hint `가 적절한 값으로 설정되어 있는지 확인하는 것이 중요합니다. 자식 위젯에 표준 ` QWidget `가 사용되는 경우, 위젯의 내용이 스크롤 영역 내에서 올바르게 표시되도록 보장하기 위해 ` QWidget::setMinimumSize()`를 호출해야 할 수도 있습니다.
레이아웃에 배치된 자식 위젯을 포함하는 위젯의 내용을 표시하기 위해 스크롤 영역을 사용하는 경우, 레이아웃의 크기 정책이 해당 위젯의 크기도 결정한다는 점을 유의해야 합니다. 이는 레이아웃의 내용을 동적으로 변경하려는 경우 특히 유용한 정보입니다. 이러한 경우, 레이아웃의 ` size constraint ` 속성을 레이아웃의 최소 및/또는 최대 크기에 제약을 주는 값(예: ` QLayout::SetMinAndMaxSize`)으로 설정하면, 레이아웃의 내용이 변경될 때마다 스크롤 영역의 크기도 업데이트됩니다.
QAbstractScrollArea 및 QScrollBar항목도 참조하십시오 .
속성 설명서
alignment : Qt::Alignment
이 속성은 스크롤 영역 위젯의 정렬 방식을 지정합니다.
유효한 정렬 방식은 다음 플래그들의 조합입니다:
Qt::AlignLeftQt::AlignHCenterQt::AlignRightQt::AlignTopQt::AlignVCenterQt::AlignBottom
기본적으로 위젯은 스크롤 영역의 왼쪽 상단 모서리에 고정됩니다.
액세스 함수:
| Qt::Alignment | alignment() const |
| void | setAlignment(Qt::Alignment) |
widgetResizable : bool
이 속성은 스크롤 영역이 뷰 위젯의 크기를 조정해야 하는지 여부를 지정합니다.
이 속성이 false(기본값)로 설정된 경우, 스크롤 영역은 해당 위젯의 크기를 그대로 따릅니다. 이 속성 설정과 관계없이 widget()->resize()을 사용하여 프로그래밍 방식으로 위젯의 크기를 조정할 수 있으며, 스크롤 영역은 새로운 크기에 맞춰 자동으로 조정됩니다.
이 속성이 true로 설정된 경우, 스크롤 영역은 스크롤 막대가 필요 없는 곳에서는 이를 방지하거나 여유 공간을 활용하기 위해 위젯의 크기를 자동으로 조정합니다.
액세스 함수:
| bool | widgetResizable() const |
| void | setWidgetResizable(bool resizable) |
멤버 함수 문서
[explicit] QScrollArea::QScrollArea(QWidget *parent = nullptr)
지정된 parent 를 사용하여 빈 스크롤 영역을 생성합니다.
setWidget()도 참조하십시오 .
[virtual noexcept] QScrollArea::~QScrollArea()
스크롤 영역과 그 자식 위젯을 제거합니다.
setWidget()도 참조하십시오 .
void QScrollArea::ensureVisible(int x, int y, int xmargin = 50, int ymargin = 50)
(x, y) 지점이 xmargin 및 ymargin 에서 픽셀 단위로 지정된 여백을 가진 뷰포트 영역 내에 보이도록 스크롤 영역의 내용을 스크롤합니다. 지정된 지점에 도달할 수 없는 경우, 내용은 가장 가까운 유효한 위치로 스크롤됩니다. 두 여백의 기본값은 모두 50 픽셀입니다.
void QScrollArea::ensureWidgetVisible(QWidget *childWidget, int xmargin = 50, int ymargin = 50)
QScrollArea::widget()의 ` childWidget `가 xmargin 및 ymargin 에서 픽셀 단위로 지정된 여백을 적용하여 뷰포트 내에 보이도록 스크롤 영역의 내용을 스크롤합니다. 지정된 지점에 도달할 수 없는 경우, 내용은 가장 가까운 유효한 위치로 스크롤됩니다. 두 여백의 기본값은 모두 50픽셀입니다.
[override virtual protected] bool QScrollArea::event(QEvent *e)
QAbstractScrollArea::event(QEvent *event)를 재구현합니다.
[override virtual protected] bool QScrollArea::eventFilter(QObject *o, QEvent *e)
QObject::eventFilter(QObject *watched, QEvent *event)를 재구현합니다.
[override virtual] bool QScrollArea::focusNextPrevChild(bool next)
QWidget::focusNextPrevChild(bool next)를 재구현합니다.
[override virtual protected] void QScrollArea::resizeEvent(QResizeEvent *)
QAbstractScrollArea::resizeEvent(QResizeEvent *event)를 재구현합니다.
[override virtual protected] void QScrollArea::scrollContentsBy(int dx, int dy)
QAbstractScrollArea::scrollContentsBy(int dx, int dy)를 재구현합니다.
void QScrollArea::setWidget(QWidget *widget)
스크롤 영역의 ` widget`를 설정합니다.
widget 는 스크롤 영역의 자식 요소가 되며, 스크롤 영역이 삭제되거나 새로운 위젯이 설정될 때 파괴됩니다.
위젯의 autoFillBackground 속성은 true 로 설정됩니다.
widget 가 추가될 때 스크롤 영역이 표시되어 있다면, 명시적으로 show()를 호출해야 합니다.
이 함수를 호출하기 전에 widget 의 레이아웃을 추가해야 합니다. 나중에 추가할 경우, 스크롤 영역에 대해 show()을 호출하는 시점과 관계없이 widget 가 표시되지 않습니다. 이 경우, 나중에 widget 에 대해 show()을 호출할 수도 없습니다.
widget()도 참조하십시오 .
[override virtual] QSize QScrollArea::sizeHint() const
QAbstractScrollArea::sizeHint() const를 재구현합니다.
QWidget *QScrollArea::takeWidget()
스크롤 영역의 위젯을 제거하고, 해당 위젯의 소유권을 호출자에게 넘깁니다.
widget()도 참조하십시오 .
[override virtual protected] QSize QScrollArea::viewportSizeHint() const
QAbstractScrollArea::viewportSizeHint() const를 재구현합니다.
QWidget *QScrollArea::widget() const
스크롤 영역의 위젯을 반환하거나, 위젯이 없는 경우 ` nullptr `를 반환합니다.
setWidget()도 참조하십시오 .
© 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.


