QProgressBar Class
QProgressBar 위젯은 가로 또는 세로 진행률 표시줄을 제공합니다. 더 보기...
| 헤더: | #include <QProgressBar> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| 상속: | QWidget |
공개 유형
| enum | Direction { TopToBottom, BottomToTop } |
속성
|
|
공개 함수
| QProgressBar(QWidget *parent = nullptr) | |
| virtual | ~QProgressBar() |
| Qt::Alignment | alignment() const |
| QString | format() const |
| bool | invertedAppearance() const |
| bool | isTextVisible() const |
| int | maximum() const |
| int | minimum() const |
| Qt::Orientation | orientation() const |
| void | resetFormat() |
| void | setAlignment(Qt::Alignment alignment) |
| void | setFormat(const QString &format) |
| void | setInvertedAppearance(bool invert) |
| void | setTextDirection(QProgressBar::Direction textDirection) |
| void | setTextVisible(bool visible) |
| virtual QString | text() const |
| QProgressBar::Direction | textDirection() const |
| int | value() const |
재구현된 공용 함수
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
공개 슬롯
| void | reset() |
| void | setMaximum(int maximum) |
| void | setMinimum(int minimum) |
| void | setOrientation(Qt::Orientation) |
| void | setRange(int minimum, int maximum) |
| void | setValue(int value) |
신호
| void | valueChanged(int value) |
보호된 함수
| virtual void | initStyleOption(QStyleOptionProgressBar *option) const |
재구현된 보호 함수
| virtual bool | event(QEvent *e) override |
| virtual void | paintEvent(QPaintEvent *) override |
상세 설명

진행률 표시줄은 사용자에게 작업 진행 상황을 알려주고, 애플리케이션이 여전히 실행 중임을 안심시키기 위해 사용됩니다.
진행률 표시줄은 ‘단계’라는 개념을 사용합니다. 가능한 최소 및 최대 단계 값을 지정하여 설정하면, 나중에 현재 단계 값을 전달했을 때 완료된 단계의 백분율이 표시됩니다. 이 백분율은 진행률(value() - minimum())을 maximum() - minimum()로 나눈 값으로 계산됩니다.
setMinimum() 및 setMaximum 을 사용하여 최소 및 최대 단계 수를 지정할 수 있습니다. 현재 단계 수는 setValue()로 설정됩니다. 진행률 표시줄은 reset()을 사용하여 시작점으로 되돌릴 수 있습니다.
최소값과 최대값을 모두 0으로 설정하면, 진행률 표시줄에는 단계별 진행률 대신 처리 중 표시기가 나타납니다. 이는 예를 들어, QNetworkAccessManager 를 사용하여 다운로드하는 항목의 크기를 파악할 수 없는 경우에 유용합니다.
QProgressDialog도 참조하십시오 .
멤버 유형 설명서
enum QProgressBar::Direction
수직 진행률 표시줄의 경우, text 의 읽기 방향을 지정합니다.
| 상수 | 값 | 설명 |
|---|---|---|
QProgressBar::TopToBottom | 0 | 텍스트가 시계 방향으로 90도 회전합니다. |
QProgressBar::BottomToTop | 1 | 텍스트가 시계 반대 방향으로 90도 회전됩니다. |
텍스트가 그려지는지 여부는 스타일에 따라 달라집니다. 현재 CleanLooks 및 Plastique 스타일에서는 텍스트가 그려지지만, Mac, Windows 및 Windows Vista 스타일에서는 그려지지 않습니다.
textDirection도 참조하십시오 .
속성 설명서
alignment : Qt::Alignment
이 속성은 진행률 표시줄의 정렬 방식을 지정합니다.
액세스 함수:
| Qt::Alignment | alignment() const |
| void | setAlignment(Qt::Alignment alignment) |
format : QString
이 속성은 현재 텍스트를 생성하는 데 사용되는 문자열을 저장합니다.
%p - 완료된 비율로 대체됩니다. %v - 현재 값으로 대체됩니다. %m - 총 단계 수로 대체됩니다.
기본값은 "%p%"입니다.
액세스 함수:
| QString | format() const |
| void | setFormat(const QString &format) |
| void | resetFormat() |
text()도 참조하십시오 .
invertedAppearance : bool
이 속성은 진행률 표시줄이 진행 상황을 반전하여 표시할지 여부를 결정합니다.
이 속성이 ` true`인 경우, 진행률 표시줄은 반대 방향(예: 오른쪽에서 왼쪽으로)으로 채워집니다. 기본적으로 진행률 표시줄은 반전되지 않습니다.
액세스 함수:
| bool | invertedAppearance() const |
| void | setInvertedAppearance(bool invert) |
orientation 및 layoutDirection도 참조하십시오 .
maximum : int
이 속성은 진행률 표시줄의 최대값을 저장합니다.
이 속성을 설정할 때, 범위가 유효한 상태를 유지하도록 필요에 따라 minimum 가 조정됩니다. 현재 값이 새로운 범위 밖으로 벗어나는 경우, ` reset()`를 통해 진행률 표시줄이 재설정됩니다.
액세스 함수:
| int | maximum() const |
| void | setMaximum(int maximum) |
minimum : int
이 속성은 진행률 표시줄의 최소값을 지정합니다.
이 속성을 설정할 때, 범위가 유효한 상태를 유지하도록 필요에 따라 maximum 가 조정됩니다. 현재 값이 새로운 범위 밖으로 벗어나는 경우, reset()를 통해 진행률 표시줄이 재설정됩니다.
액세스 함수:
| int | minimum() const |
| void | setMinimum(int minimum) |
orientation : Qt::Orientation
이 속성은 진행률 표시줄의 방향을 지정합니다.
방향은 Qt::Horizontal (기본값) 또는 Qt::Vertical 이어야 합니다.
액세스 함수:
| Qt::Orientation | orientation() const |
| void | setOrientation(Qt::Orientation) |
invertedAppearance 및 textDirection도 참조하십시오 .
[read-only] text : QString
이 속성은 진행률 표시줄과 함께 표시되는 설명 텍스트를 저장합니다.
반환되는 텍스트는 진행률 표시줄의 중앙(또는 일부 스타일의 경우 왼쪽)에 표시되는 텍스트와 동일합니다.
텍스트에 표시된 진행률은 최소값보다 작을 수 있으며, 이는 진행률이 설정되기 전 진행률 표시줄이 "재설정" 상태에 있음을 나타냅니다.
기본 구현에서 텍스트에는 현재까지의 진행 상황을 나타내는 백분율 값이 포함되거나, 진행률 표시줄이 재설정 상태이므로 비어 있습니다.
액세스 함수:
| virtual QString | text() const |
textDirection : Direction
이 속성은 세로 진행률 막대( text )의 읽기 방향을 지정합니다.
이 속성은 가로 진행률 표시줄에는 영향을 미치지 않습니다. 기본적으로 읽기 방향은 ' QProgressBar::TopToBottom'입니다.
액세스 함수:
| QProgressBar::Direction | textDirection() const |
| void | setTextDirection(QProgressBar::Direction textDirection) |
orientation 및 textVisible도 참조하십시오 .
textVisible : bool
이 속성은 현재 완료율을 표시할지 여부를 결정합니다.
이 속성은 스타일에서 무시될 수 있습니다(예: QMacStyle은 텍스트를 절대 그리지 않습니다).
액세스 함수:
| bool | isTextVisible() const |
| void | setTextVisible(bool visible) |
textDirection도 참조하십시오 .
value : int
이 속성은 진행률 막대의 현재 값을 저장합니다.
최소-최대 범위를 벗어난 값으로 현재 값을 변경하려고 시도해도 현재 값에는 아무런 영향이 없습니다.
액세스 함수:
| int | value() const |
| void | setValue(int value) |
알림 신호:
| void | valueChanged(int value) |
멤버 함수 설명서
[explicit] QProgressBar::QProgressBar(QWidget *parent = nullptr)
지정된 parent 를 사용하여 진행률 표시줄을 생성합니다.
기본적으로 최소 단계 값은 0으로, 최대 단계 값은 100으로 설정됩니다.
setRange()도 참조하십시오 .
[virtual noexcept] QProgressBar::~QProgressBar()
소멸자.
[override virtual protected] bool QProgressBar::event(QEvent *e)
QWidget::event(QEvent *event)을 재구현합니다.
[virtual protected] void QProgressBar::initStyleOption(QStyleOptionProgressBar *option) const
option 를 QProgressBar 에 있는 값들로 초기화합니다. 이 방법은 하위 클래스에서 QStyleOptionProgressBar 가 필요하지만, 모든 정보를 직접 입력하고 싶지 않을 때 유용합니다.
QStyleOption::initFrom()도 참조하십시오 .
[override virtual] QSize QProgressBar::minimumSizeHint() const
QWidget::minimumSizeHint 속성에 대한 액세스 함수를 재구현합니다.
[override virtual protected] void QProgressBar::paintEvent(QPaintEvent *)
QWidget::paintEvent(QPaintEvent *event)를 재구현합니다.
[slot] void QProgressBar::reset()
진행률 표시줄을 초기화합니다. 진행률 표시줄이 “되감기”되어 진행 상황이 표시되지 않습니다.
[slot] void QProgressBar::setRange(int minimum, int maximum)
진행률 표시줄의 최소값과 최대값을 각각 minimum 및 maximum 로 설정합니다.
maximum 가 minimum 보다 작을 경우, minimum 가 유효한 유일한 값이 됩니다.
현재 값이 새로운 범위 밖으로 벗어나는 경우, 진행률 표시줄은 reset()을 사용하여 재설정됩니다.
QProgressBar 는 setRange(0, 0)을 사용하여 미정 상태로 설정할 수 있습니다.
[override virtual] QSize QProgressBar::sizeHint() const
QWidget::sizeHint 속성에 대한 액세스 함수를 다시 구현합니다.
[signal] void QProgressBar::valueChanged(int value)
이 신호는 진행률 표시줄에 표시된 값이 변경될 때 발생합니다. ` value `는 진행률 표시줄에 새로 표시되는 값입니다.
참고: value 속성에 대한알림 신호입니다.
© 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.