QDataWidgetMapper Class

연꿀

21 5월 2025 • 2 min read

PySide6 `QDataWidgetMapper` 상세 설명

QDataWidgetMapper는 데이터 모델(QAbstractItemModel)과 위젯을 매핑해주는 클래스로, 모델-뷰 아키텍처에서 폼 기반 애플리케이션을 쉽게 구현할 수 있게 합니다.

🌟 주요 특징

class SubmitPolicy(enum.Enum):
    AutoSubmit = 0x0  # 자동 저장(기본값)
    ManualSubmit = 0x1  # 수동 저장

SubmitPolicy: 데이터 저장 시점 제어
- AutoSubmit: 위젯 값 변경 시 즉시 모델에 반영
- ManualSubmit: submit() 호출 시에만 반영

🔨 주요 메서드 분석

1. 매핑 설정

def addMapping(widget, section, propertyName=...)

widget: 매핑할 위젯 (예: QLineEdit)
section: 모델의 컬럼/로우 인덱스
propertyName: 사용할 위젯 프로퍼티 (기본값: 자동 감지)

2. 네비게이션

toFirst()  # 첫 번째 레코드
toLast()   # 마지막 레코드
toNext()   # 다음 레코드
toPrevious()  # 이전 레코드

3. 데이터 관리

submit()  # 변경사항 저장
revert()  # 변경사항 취소
currentIndex()  # 현재 인덱스 반환

🚀 핵심 기능 활용법

기본 사용 예시

mapper = QDataWidgetMapper()
mapper.setModel(model)  # QAbstractItemModel 연결
mapper.addMapping(name_edit, 0)  # 0번 컬럼 매핑
mapper.addMapping(age_spinbox, 1, b"value")  # 프로퍼티 명시적 지정
mapper.toFirst()  # 첫 번째 데이터 표시

커스텀 프로퍼티 매핑

# QLabel의 pixmap 프로퍼티에 매핑
mapper.addMapping(image_label, 2, QByteArray(b"pixmap"))

⚠️ 주의사항 & 팁

Orientation 설정

setOrientation(Qt.Vertical)  # 기본값: 컬럼 기준 매핑
setOrientation(Qt.Horizontal)  # 로우 기준 매핑

델리게이트 활용

delegate = MyCustomDelegate()
setItemDelegate(delegate)  # 데이터 렌더링/편집 방식 커스터마이징

신호 활용

mapper.currentIndexChanged.connect(lambda i: print(f"현재 인덱스: {i}"))

🔄 전형적인 작업 흐름

모델 생성 (SQL, CSV, 커스텀 데이터 등)
매퍼에 모델 연결
위젯-컬럼 매핑 설정
네비게이션 메서드로 데이터 탐색
SubmitPolicy에 따라 데이터 저장 처리

이 클래스를 활용하면 데이터베이스 레코드 탐색기, 설정 창, 데이터 입력 폼 등을 쉽게 구현할 수 있습니다. QTableView와 달리 위젯 기반 UI에 최적화된 것이 가장 큰 장점입니다! 🎉

Perplexity로부터의 답변: pplx.ai/share

PySide6 QDataWidgetMapper 상세 설명