QProgressBar 개요

QProgressBar는 PyQt5에서 작업 진행 상황을 시각적으로 표현하는 위젯입니다. 파일 전송, 데이터 변환, 리소스 로딩 등 다양한 상황에서 사용자에게 현재 상태를 전달하며, 수치 기반 진행 표시와 애니메이션 기반 불확실 모드를 모두 지원합니다.

주요 특성

• 방향 설정: 가로 또는 세로 배치 선택 가능
• 수치 범위: 임의의 최소·최대값 지정 (기본 0~100)
• 텍스트 포맷: 퍼센트, 현재값, 최대값 등 동적 문자열 구성
• 불확실 모드: 완료 시점을 예측할 수 없는 작업용 애니메이션
• 스타일 시트: 색상, 모양, 애니메이션 간격 등 외관 커스터마이징

생성 및 기본 설정

from PyQt5.QtWidgets import QProgressBar

bar = QProgressBar(parent)
bar.setMinimum(0)
bar.setMaximum(100)
bar.setValue(25)

핵심 메서드 분류

범위 및 값 제어

표시 형태 설정

포맷 코드

• %p: 백분율 (자동 계산)
• %v: 현재 수치
• %m: 최대 수치

불확실 모드 전환

작업 완료 시점을 알 수 없을 때 유용합니다. 범위를 (0, 0)으로 설정하면 자동으로 애니메이션 모드로切換됩니다.

# 불확실 모드 활성화
bar.setRange(0, 0)
bar.setFormat("처리 중...")

# 확정 모드 복귀
bar.setRange(0, 100)
bar.setValue(0)

실전 예제

예제 1: 기본 진행 표시

import time
from threading import Thread
from PyQt5.QtWidgets import (
    QApplication, QWidget, QVBoxLayout,
    QPushButton, QProgressBar
)


class BasicProgress(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("진행률 표시 데모")

        self.indicator = QProgressBar()
        self.indicator.setRange(0, 100)
        self.indicator.setFormat("완료율: %p%")

        self.action_btn = QPushButton("시작")
        self.action_btn.clicked.connect(self.launch_task)

        container = QVBoxLayout()
        container.addWidget(self.indicator)
        container.addWidget(self.action_btn)
        self.setLayout(container)

    def launch_task(self):
        def background_work():
            for step in range(101):
                self.indicator.setValue(step)
                QApplication.processEvents()
                time.sleep(0.03)

        Thread(target=background_work, daemon=True).start()


if __name__ == "__main__":
    app = QApplication([])
    demo = BasicProgress()
    demo.show()
    app.exec_()

예제 2: 불확실 상태 애니메이션

class LoadingSpinner(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("로딩 애니메이션")

        self.spinner = QProgressBar()
        self.spinner.setRange(0, 0)
        self.spinner.setFormat("데이터 수신 중...")

        box = QVBoxLayout()
        box.addWidget(self.spinner)
        self.setLayout(box)

예제 3: 스타일 커스터마이징

self.indicator.setStyleSheet("""
    QProgressBar {
        border: 1px solid #8f8f8f;
        border-radius: 4px;
        background-color: #f0f0f0;
        text-align: center;
        height: 24px;
    }
    QProgressBar::chunk {
        background-color: qlineargradient(
            x1: 0, y1: 0, x2: 1, y2: 0,
            stop: 0 #4facfe,
            stop: 1 #00f2fe
        );
        border-radius: 3px;
    }
""")

시그 활용

값 변화를 감지하여 다른 위젯과 연동할 수 있습니다.

def on_percentage_changed(self, current):
    if current >= 100:
        self.status_label.setText("작업 완료!")

bar.valueChanged.connect(self.on_percentage_changed)

주의사항

• 스레드 안전: GUI 위젯은 메인 스레드에서만 조작해야 하며, QThread나 신호-슬롯 메커니즘을 권장합니다
• 업데이트 빈도: 과도한 갱신은 렌더링 부하를 유발하므로, 필요시 time.sleep 또는 타이머로 조절
• 불확실 모드 전환: 작업 종료 후 반드시 확정 모드로 복원하여 사용자 혼란 방지