PySide(Qt for Python) 컨테이너 QGroupBox, QTabWidget, QStackedWidget, QSplitter 동적 show, hide 실전 가이드

PySide(Qt for Python) 컨테이너 QGroupBox, QTabWidget, QStackedWidget, QSplitter 동적 show, hide 실전 가이드

🧭 클릭 한 번으로 화면을 바꾸는 레이아웃 설계법과 위젯 컨테이너 활용 포인트를 정리합니다

데스크톱 앱을 만들다 보면 버튼을 눌렀을 때 특정 영역만 감추거나 보여 주고, 탭 간에 깔끔하게 전환되며, 패널의 너비를 자유롭게 조절하는 경험이 얼마나 중요한지 자연스럽게 깨닫게 됩니다.
PySide는 Qt의 강력한 레이아웃 시스템을 그대로 품고 있어 이러한 요구를 구조적으로 해결할 수 있습니다.
이 글은 컨테이너 위젯인 QGroupBox, QTabWidget, QStackedWidget, QSplitter를 중심으로 실제 프로젝트에서 바로 적용 가능한 설계 관점과 사용 패턴을 안내합니다.
기본 개념을 빠르게 짚은 다음, 동적 show, hide를 이용해 화면 흐름을 제어하는 방법까지 차근차근 살펴볼 수 있도록 구성했습니다.

우선 어떤 컨테이너를 선택하느냐가 전체 UX를 좌우합니다.
설정 그룹을 묶어 가독성을 높일지, 기능을 탭으로 분리할지, 상태에 따라 화면을 전환할지, 혹은 작업 흐름에 맞춰 화면을 좌우로 나누어 병행할지를 결정하는 일이죠.
여기에 동적 표시와 숨김 제어를 결합하면 복잡한 폼과 도구 패널도 간결하게 유지할 수 있습니다.
각 컨테이너의 특징을 비교하면서 언제 어떤 선택이 합리적인지, 시그널과 슬롯으로 인터랙션을 연결하는 방식까지 알기 쉽게 정리했습니다.

📦 컨테이너 개요와 선택 기준

PySide(Qt for Python)의 컨테이너는 화면 구조를 정의하고 상호작용의 경계를 만드는 핵심 도구입니다.
QGroupBox는 관련 위젯을 시각적으로 묶어 가독성을 높이고, QTabWidget은 동일 계층의 기능을 탭으로 병렬 배치합니다.
QStackedWidget은 상태나 단계에 따라 서로 다른 화면을 같은 자리에서 교차 표시하고, QSplitter는 두 개 이상의 패널을 사용자가 직접 크기 조절할 수 있게 합니다.
동적 show, hide 제어와 결합하면 복잡한 폼이나 도구 패널도 간결하게 유지되며, 불필요한 재레이아웃을 최소화해 성능과 사용성을 함께 확보할 수 있습니다.

선택 기준은 콘텐츠의 관계성과 전환 패턴을 먼저 정의하는 것에서 출발합니다.
독립된 설정 묶음이 필요하면 QGroupBox, 상호 배타적인 기능 그룹이라면 QTabWidget, 단계 기반 워크플로우나 권한·상태별 화면이라면 QStackedWidget이 적합합니다.
작업 중 비교·병행이 필요하고 화면 비율을 사용자가 조정해야 한다면 QSplitter가 효율적입니다.
여기에 표시 조건을 이벤트(체크박스, 콤보 선택, 비동기 처리 완료 등)로 연결하고 setVisible, show, hide, setCurrentIndex 같은 API로 전환을 명시하면 유지보수가 쉬운 구조를 만들 수 있습니다.

from PySide6.QtWidgets import (
    QApplication, QWidget, QVBoxLayout, QHBoxLayout,
    QGroupBox, QCheckBox, QTabWidget, QStackedWidget,
    QPushButton, QLabel, QSplitter, QTextEdit
)
from PySide6.QtCore import Qt

app = QApplication([])

root = QWidget()
root.setWindowTitle("컨테이너·동적 show/hide 예시")
layout = QVBoxLayout(root)

# 1) QGroupBox: 체크 가능 그룹
grp = QGroupBox("고급 설정")
grp.setCheckable(True)
grp.setChecked(False)  # 기본 비활성
g_lay = QVBoxLayout(grp)
g_lay.addWidget(QCheckBox("로그 저장"))
g_lay.addWidget(QCheckBox("세션 복원"))

# 2) QTabWidget: 탭 인터페이스
tabs = QTabWidget()
tabs.addTab(QLabel("일반 옵션"), "일반")
tabs.addTab(QLabel("네트워크 옵션"), "네트워크")

# 3) QStackedWidget: 상태별 화면 전환
stack = QStackedWidget()
page_login = QWidget(); page_main = QWidget()
page_login.setLayout(QVBoxLayout()); page_login.layout().addWidget(QLabel("로그인 화면"))
btn_login = QPushButton("로그인")
page_login.layout().addWidget(btn_login)
page_main.setLayout(QVBoxLayout()); page_main.layout().addWidget(QLabel("메인 대시보드"))
stack.addWidget(page_login)
stack.addWidget(page_main)

def do_login():
    stack.setCurrentIndex(1)  # 화면 전환
btn_login.clicked.connect(do_login)

# 4) QSplitter: 가변 분할
splitter = QSplitter(Qt.Horizontal)
splitter.addWidget(QTextEdit("왼쪽 패널"))
splitter.addWidget(QTextEdit("오른쪽 패널"))
splitter.setSizes([300, 500])  # 초기 너비 비율

# 동적 show/hide: 버튼으로 그룹 숨김/표시
btn_toggle = QPushButton("고급 설정 표시/숨기기")
def toggle_group():
    grp.setVisible(not grp.isVisible())
btn_toggle.clicked.connect(toggle_group)

layout.addWidget(btn_toggle)
layout.addWidget(grp)
layout.addWidget(tabs)
layout.addWidget(stack)
layout.addWidget(splitter)

root.show()
app.exec()

• 🧭기능 관계를 먼저 분류하고 그룹·탭·상태 전환·분할 중 무엇이 맞는지 결정합니다.
• ⚙️표시 조건을 이벤트로 명시하고 setVisible·show/hide·setCurrentIndex로 전환을 구현합니다.
• 🧪비동기 작업(예: 로그인, 로딩)에는 플레이스홀더 화면을 두고 전환 시점을 명확히 테스트합니다.

💬 컨테이너 선택은 배치(Layout)보다 먼저 결정하면 시행착오를 줄일 수 있습니다.
역할·전환·사용자 제어 세 축으로 기준을 세우면 구조가 선명해집니다.

🧩 QGroupBox 활용 패턴과 체크 가능 그룹

QGroupBox는 여러 위젯을 하나의 그룹으로 묶고, 시각적인 프레임과 제목을 제공하는 컨테이너입니다.
폼 기반 UI에서 설정 항목을 논리적으로 구분하거나, 관련 옵션을 묶어 한눈에 보기 좋게 만드는 데 자주 사용됩니다.
특히 checkable 속성을 활성화하면 그룹 전체를 켜고 끌 수 있는 스위치처럼 동작시킬 수 있습니다.
이 경우 사용자는 체크박스 하나로 여러 옵션을 동시에 제어할 수 있고, 내부 위젯을 활성화 또는 비활성화하는 코드 제어도 간단해집니다.

QGroupBox는 QVBoxLayout 또는 QHBoxLayout을 함께 사용하는 것이 일반적이며, 그룹의 제목은 시각적 힌트를 주기 때문에 과도하게 중첩하지 않도록 주의해야 합니다.
또한 그룹 내 위젯이 많아질 경우 스크롤 영역(QScrollArea)과 결합하면 스크롤 가능한 설정 블록을 구성할 수 있습니다.
이 구조는 환경설정 창이나 고급 설정 패널에 특히 유용합니다.

⚙️ QGroupBox의 기본 구조와 시그널 연결

from PySide6.QtWidgets import QApplication, QWidget, QGroupBox, QVBoxLayout, QCheckBox
from PySide6.QtCore import Qt

app = QApplication([])

window = QWidget()
layout = QVBoxLayout(window)

group = QGroupBox("고급 설정")
group.setCheckable(True)
group.setChecked(False)

opt1 = QCheckBox("자동 로그 저장")
opt2 = QCheckBox("세션 복원")

# 그룹 내 레이아웃
g_layout = QVBoxLayout(group)
g_layout.addWidget(opt1)
g_layout.addWidget(opt2)

# 그룹이 체크되면 내부 활성화
def on_group_toggled(state):
    for cb in (opt1, opt2):
        cb.setEnabled(state)

group.toggled.connect(on_group_toggled)

layout.addWidget(group)
window.show()
app.exec()

위 코드에서는 그룹 전체가 비활성 상태로 시작하며, 사용자가 그룹 상단의 체크박스를 클릭하면 내부 옵션이 함께 활성화됩니다.
이 패턴은 설정 화면에서 “고급 옵션” 또는 “세부 설정 보기” 같은 항목에 자주 활용됩니다.
이처럼 QGroupBox는 논리적 구획과 동적 제어를 동시에 제공한다는 점에서 매우 유용한 위젯입니다.

🧠 QGroupBox의 동적 표시/숨김 활용

때로는 단순히 활성/비활성뿐 아니라, 전체 그룹을 감추거나 표시해야 할 때도 있습니다.
이럴 때는 setVisible(), show(), hide() 메서드를 사용하면 됩니다.
예를 들어 사용자가 체크박스를 클릭할 때 특정 설정 그룹을 보여 주거나 감추는 인터랙션을 구성할 수 있습니다.

toggle_box = QCheckBox("고급 설정 표시")
toggle_box.setChecked(False)

def toggle_visibility(state):
    group.setVisible(state)

toggle_box.toggled.connect(toggle_visibility)
layout.insertWidget(0, toggle_box)

이 방식은 UI를 간결하게 유지하면서도 필요할 때만 세부 설정을 보여 줄 수 있어 사용자 경험을 크게 향상시킵니다.
또한 layout.setSpacing()과 setContentsMargins()을 적절히 조정하면 숨김 시 공간 낭비도 줄일 수 있습니다.

🗂️ QTabWidget로 탭형 인터페이스 구성

QTabWidget은 하나의 영역 안에 여러 페이지를 탭 형태로 배치할 수 있는 컨테이너입니다.
웹 브라우저의 탭처럼 직관적인 전환이 가능하며, 사용자 입장에서 서로 관련된 기능들을 빠르게 이동할 수 있습니다.
PySide에서 QTabWidget은 addTab() 또는 insertTab() 메서드로 페이지를 추가하며, 각 탭에는 고유한 위젯이 들어갑니다.
이 위젯 안에는 다시 QVBoxLayout, QFormLayout 등 다양한 구성 요소를 자유롭게 배치할 수 있습니다.

탭 전환은 내부적으로 QStackedWidget을 사용하기 때문에, 실제로는 여러 페이지를 한 영역에서 인덱스로 관리합니다.
이 덕분에 show/hide를 직접 다루지 않아도 전환이 부드럽고, 상태 유지를 위한 별도 관리가 필요 없습니다.
또한 currentChanged(int) 시그널을 이용하면 사용자가 어떤 탭으로 이동했는지 감지할 수 있으며, 이에 따라 동적 데이터 로딩이나 UI 업데이트를 구현할 수도 있습니다.

📁 탭 생성과 전환 이벤트 처리

from PySide6.QtWidgets import QApplication, QWidget, QTabWidget, QVBoxLayout, QLabel

app = QApplication([])

window = QWidget()
layout = QVBoxLayout(window)

tabs = QTabWidget()

tab_general = QWidget()
tab_network = QWidget()
tab_about = QWidget()

tab_general.setLayout(QVBoxLayout())
tab_general.layout().addWidget(QLabel("일반 설정 페이지"))

tab_network.setLayout(QVBoxLayout())
tab_network.layout().addWidget(QLabel("네트워크 설정 페이지"))

tab_about.setLayout(QVBoxLayout())
tab_about.layout().addWidget(QLabel("정보 페이지"))

tabs.addTab(tab_general, "일반")
tabs.addTab(tab_network, "네트워크")
tabs.addTab(tab_about, "정보")

def on_tab_changed(index):
    print("현재 탭:", tabs.tabText(index))

tabs.currentChanged.connect(on_tab_changed)

layout.addWidget(tabs)
window.show()
app.exec()

위 예제처럼 각 탭에는 독립된 레이아웃을 설정하며, 전환 이벤트는 currentChanged 시그널로 처리합니다.
탭의 순서나 아이콘, 닫기 버튼 등을 제어하고 싶을 때는 setTabsClosable(True)나 setTabIcon()을 이용하면 됩니다.
또한 tabPosition 속성을 변경하면 탭을 상단, 하단, 좌우로 배치할 수도 있습니다.

🧭 동적 show/hide와 탭 병합 UI

QTabWidget은 다른 컨테이너와 결합하여 유연한 화면 전환을 구현할 수도 있습니다.
예를 들어 특정 조건에서만 탭을 보여 주거나, 사용자가 선택한 모드에 따라 탭을 추가·제거할 수 있습니다.
이럴 때는 setTabVisible() 메서드로 특정 탭을 감추거나 보이게 조정할 수 있습니다 (Qt 5.15 이상).

# "정보" 탭을 숨기기
tabs.setTabVisible(2, False)

# 이후 조건이 충족되면 다시 표시
tabs.setTabVisible(2, True)

이 기법은 권한 기반 UI에서 유용하게 쓰입니다.
예를 들어 관리자 전용 설정 탭을 일반 사용자 계정에서는 숨겨 둘 수 있습니다.
또한 동적 탭 추가를 통해 플러그인 구조를 구성할 때도 효과적입니다.

🪟 QStackedWidget로 화면 전환과 상태 관리

QStackedWidget은 여러 위젯을 겹쳐서 관리하고, 현재 인덱스에 따라 하나만 표시하는 구조를 가진 컨테이너입니다.
즉, 로그인 화면과 메인 화면처럼 상호 배타적인 페이지를 한 영역에 배치하고, 인덱스를 바꿔 전환하는 방식으로 UI를 구현합니다.
여러 개의 화면을 동적으로 표시·숨김할 필요가 있을 때 show/hide보다 훨씬 효율적이며, 재레이아웃이 발생하지 않아 전환이 매우 빠릅니다.

PySide에서 QStackedWidget은 addWidget()으로 페이지를 추가하고 setCurrentIndex() 또는 setCurrentWidget()으로 활성 페이지를 변경합니다.
또한 currentChanged(int) 시그널을 통해 전환 이벤트를 처리할 수 있습니다.
이 구조는 상태 기반 UI, 단계별 마법사, 또는 탭과 달리 시나리오 중심으로 화면이 바뀌는 앱에 적합합니다.

🚀 페이지 전환 구현 예제

from PySide6.QtWidgets import QApplication, QWidget, QPushButton, QLabel, QVBoxLayout, QStackedWidget

app = QApplication([])

stack = QStackedWidget()

# 로그인 페이지
page_login = QWidget()
login_layout = QVBoxLayout(page_login)
login_layout.addWidget(QLabel("로그인 화면"))
btn_login = QPushButton("로그인")
login_layout.addWidget(btn_login)

# 메인 페이지
page_main = QWidget()
main_layout = QVBoxLayout(page_main)
main_layout.addWidget(QLabel("메인 화면"))
btn_logout = QPushButton("로그아웃")
main_layout.addWidget(btn_logout)

stack.addWidget(page_login)
stack.addWidget(page_main)

# 전환 함수
def go_main():
    stack.setCurrentIndex(1)

def go_login():
    stack.setCurrentIndex(0)

btn_login.clicked.connect(go_main)
btn_logout.clicked.connect(go_login)

stack.setWindowTitle("QStackedWidget 예제")
stack.resize(300, 200)
stack.show()
app.exec()

위 코드처럼 QStackedWidget을 사용하면 로그인과 메인 화면을 단일 창에서 전환할 수 있습니다.
별도의 창 생성 없이 하나의 윈도우 내에서 자연스럽게 페이지가 바뀌기 때문에 UX가 간결하고, 상태 관리도 단순해집니다.
또한 QStackedWidget을 다른 레이아웃 안에 포함해 부분 영역만 전환하도록 구성할 수도 있습니다.

🧭 동적 show/hide와의 결합

QStackedWidget은 자체적으로 화면 전환을 제공하지만, 필요에 따라 show/hide를 병행할 수도 있습니다.
예를 들어 특정 조건에서 스택 자체를 숨기거나, 현재 페이지 외의 위젯을 감춰야 할 때 유용합니다.
이때도 레이아웃 재계산 없이 즉시 반응하므로 복잡한 폼에서도 성능 저하가 없습니다.

# 스택 전체를 숨김
stack.hide()

# 특정 조건 충족 시 다시 표시
if user_authenticated:
    stack.show()

이처럼 show/hide는 개별 위젯의 가시성을 빠르게 전환할 때, QStackedWidget은 전체 UI의 논리적 전환을 구현할 때 각각 장점을 가집니다.
두 가지를 적절히 병행하면 사용자 흐름이 자연스러우면서도 코드 유지보수성이 높아집니다.

✂️ QSplitter로 가변 분할 레이아웃 최적화

QSplitter는 창 내부를 좌우 또는 상하로 나누어 사용자가 직접 크기를 조정할 수 있도록 하는 컨테이너입니다.
텍스트 에디터나 파일 탐색기처럼 여러 패널을 동시에 표시해야 하는 환경에서 자주 쓰입니다.
PySide에서 QSplitter는 addWidget()으로 자식 위젯을 순차적으로 추가하고, 방향을 Qt.Horizontal 또는 Qt.Vertical로 지정합니다.
이때 각 패널의 크기는 사용자가 마우스로 직접 조절할 수 있으며, 내부적으로 레이아웃이 자동 업데이트됩니다.

QSplitter의 장점은 단순한 분할뿐 아니라 setSizes()로 초기 비율을 지정하고, saveState()와 restoreState()로 사용자의 조정 상태를 기억할 수 있다는 점입니다.
이 덕분에 사용자가 창 크기를 바꾼 후에도 마지막으로 조정한 패널 비율을 그대로 복원할 수 있습니다.

🔌 코드 예제: 좌우 패널 구성

from PySide6.QtWidgets import QApplication, QWidget, QSplitter, QTextEdit, QVBoxLayout
from PySide6.QtCore import Qt

app = QApplication([])

window = QWidget()
layout = QVBoxLayout(window)

splitter = QSplitter(Qt.Horizontal)
left_panel = QTextEdit("왼쪽 패널: 코드 편집")
right_panel = QTextEdit("오른쪽 패널: 결과 또는 로그")

splitter.addWidget(left_panel)
splitter.addWidget(right_panel)

# 초기 분할 비율 설정
splitter.setSizes([400, 600])

layout.addWidget(splitter)
window.resize(1000, 600)
window.setWindowTitle("QSplitter 예제")
window.show()
app.exec()

이 코드는 가장 단순한 QSplitter 예제입니다.
좌측에는 코드 편집기, 우측에는 로그창이나 미리보기 패널을 배치해, 사용자가 중간 핸들을 드래그하여 비율을 바꿀 수 있습니다.
수평 분할(Qt.Horizontal) 대신 수직 분할(Qt.Vertical)을 지정하면 위아래로 패널을 구성할 수도 있습니다.

💾 상태 저장과 복원

QSplitter의 또 다른 강력한 기능은 상태 저장입니다.
사용자가 패널 크기를 조절한 후 프로그램을 다시 실행했을 때, 이전 크기를 유지할 수 있습니다.
이때 saveState()로 바이트 데이터를 저장하고, 다시 시작할 때 restoreState()로 복원하면 됩니다.

# 상태 저장
state = splitter.saveState()

# 다음 실행 시 복원
splitter.restoreState(state)

보통 이 상태값은 QSettings와 함께 사용하여 프로그램 종료 시 자동 저장, 실행 시 복원하도록 구현합니다.
사용자가 원하는 레이아웃을 유지할 수 있으므로, 전문 도구형 애플리케이션에서 자주 활용됩니다.

❓ 자주 묻는 질문 (FAQ)

🧭 PySide 컨테이너 구조 완전 정리

PySide(Qt for Python)의 컨테이너 위젯들은 단순히 레이아웃을 나누는 수준을 넘어, 사용자 경험(UX)과 유지보수성에 직접적인 영향을 미치는 중요한 구성 요소입니다.
이번 글에서는 QGroupBox, QTabWidget, QStackedWidget, QSplitter의 구조와 활용법, 그리고 동적 show/hide를 결합한 실전 패턴까지 모두 다뤘습니다.
이 네 가지 컨테이너는 조합에 따라 거의 모든 데스크톱 UI 구성을 커버할 수 있습니다.
예를 들어, QSplitter로 기본 레이아웃을 나누고, 각 패널 안에 QTabWidget이나 QStackedWidget을 넣는 식으로 복잡한 UI도 계층적으로 정리할 수 있습니다.

QGroupBox는 시각적 그룹화와 상태 제어에 탁월하며, QTabWidget은 기능적 구분과 빠른 전환을 제공합니다.
QStackedWidget은 상태 기반 전환 구조를 단순화하고, QSplitter는 사용자 맞춤형 크기 조정 기능을 부여합니다.
그리고 show/hide 제어는 이들 컨테이너를 상황에 맞게 조합해 보다 유연한 인터페이스를 설계할 수 있게 합니다.
이러한 패턴은 대규모 툴, IDE, 설정 관리자 등 다양한 응용 프로그램에서 널리 사용됩니다.

🏷️ 관련 태그 : PySide, QtforPython, QGroupBox, QTabWidget, QStackedWidget, QSplitter, GUI개발, PythonUI, Qt레이아웃, 동적UI