이 페이지에서

QListWidgetItem Class

QListWidgetItem 클래스는 QListWidget 항목 뷰 클래스와 함께 사용할 수 있는 항목을 제공합니다. 더 보기...

헤더: #include <QListWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets

공개 타입

enum ItemType { Type, UserType }

공개 함수

QListWidgetItem(QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)
QListWidgetItem(const QListWidgetItem &other)
virtual ~QListWidgetItem()
QBrush background() const
Qt::CheckState checkState() const
virtual QListWidgetItem *clone() const
virtual QVariant data(int role) const
Qt::ItemFlags flags() const
QFont font() const
QBrush foreground() const
QIcon icon() const
bool isHidden() const
bool isSelected() const
QListWidget *listWidget() const
virtual void read(QDataStream &in)
void setBackground(const QBrush &brush)
void setCheckState(Qt::CheckState state)
virtual void setData(int role, const QVariant &value)
void setFlags(Qt::ItemFlags flags)
void setFont(const QFont &font)
void setForeground(const QBrush &brush)
void setHidden(bool hide)
void setIcon(const QIcon &icon)
void setSelected(bool select)
void setSizeHint(const QSize &size)
void setStatusTip(const QString &statusTip)
void setText(const QString &text)
(since 6.4) void setTextAlignment(Qt::Alignment alignment)
void setToolTip(const QString &toolTip)
void setWhatsThis(const QString &whatsThis)
QSize sizeHint() const
QString statusTip() const
QString text() const
int textAlignment() const
QString toolTip() const
int type() const
QString whatsThis() const
virtual void write(QDataStream &out) const
virtual bool operator<(const QListWidgetItem &other) const
QListWidgetItem &operator=(const QListWidgetItem &other)
QDataStream &operator<<(QDataStream &out, const QListWidgetItem &item)
QDataStream &operator>>(QDataStream &in, QListWidgetItem &item)

상세 설명

QListWidgetItem은 QListWidget QListWidget 의 단일 항목을 나타냅니다. 각 항목은 여러 가지 정보를 포함할 수 있으며, 이를 적절하게 표시합니다.

항목 뷰 편의 클래스는 순수한 모델/뷰 방식보다는 전통적인 항목 기반 인터페이스를 사용합니다. 보다 유연한 목록 뷰 위젯을 원한다면, 표준 모델과 함께 QListView 클래스를 사용하는 것을 고려해 보십시오.

목록 항목은 생성 시 목록 위젯을 지정하여 목록에 자동으로 삽입될 수 있습니다:

new QListWidgetItem(tr("Hazel"), listWidget);

또는, 목록 항목을 부모 위젯 없이 생성한 후, 나중에 ` QListWidget::insertItem()`를 사용하여 목록에 삽입할 수도 있습니다.

목록 항목은 일반적으로 text() 및 icon()을 표시하는 데 사용됩니다. 이들은 setText() 및 setIcon() 함수를 사용하여 설정됩니다. 텍스트의 모양은 setFont(), setForeground(), setBackground()을 사용하여 사용자 정의할 수 있습니다. 목록 항목 내의 텍스트는 setTextAlignment() 함수를 사용하여 정렬할 수 있습니다. setToolTip(), setStatusTip() 및 setWhatsThis()을 사용하여 목록 항목에 툴팁, 상태 팁 및 "이게 뭐죠?" 도움말을 추가할 수 있습니다.

기본적으로 항목은 활성화되어 있으며, 선택 및 체크가 가능하고, 드래그 앤 드롭 작업의 대상이 될 수 있습니다.

각 항목의 플래그는 적절한 값을 사용하여 setFlags()을 호출하여 변경할 수 있습니다( Qt::ItemFlags 참조). 체크 가능한 항목은 setCheckState() 함수를 사용하여 체크, 체크 해제 및 부분 체크할 수 있습니다. 이에 대응하는 checkState() 함수는 항목의 현재 체크 상태를 나타냅니다.

isHidden() 함수를 사용하여 항목이 숨겨져 있는지 확인할 수 있습니다. 항목을 숨기려면 setHidden()를 사용하십시오.

서브클래싱

사용자 정의 항목을 제공하기 위해 QListWidgetItem을 상속할 때, 표준 항목과 구별될 수 있도록 해당 항목에 대한 새로운 유형을 정의할 수 있습니다. 이 기능이 필요한 하위 클래스의 경우, 생성자 내에서 UserType 보다 크거나 같은 새로운 유형 값을 사용하여 기본 클래스 생성자를 호출해야 합니다.

QListWidget, 모델/뷰 프로그래밍, QTreeWidgetItem 및 QTableWidgetItem도 참조하십시오 .

멤버 유형 문서

enum QListWidgetItem::ItemType

이 열거형은 목록 위젯 항목을 설명하는 데 사용되는 유형들을 정의합니다.

상수값설명
QListWidgetItem::Type0목록 위젯 항목의 기본 유형입니다.
QListWidgetItem::UserType1000사용자 정의 유형의 최소 값입니다. UserType보다 작은 값은 Qt에서 예약되어 있습니다.

QListWidgetItem 의 서브클래스에서 새로운 사용자 유형을 정의하여 사용자 정의 항목이 특별히 처리되도록 할 수 있습니다.

type()도 참조하십시오 .

멤버 함수 문서

[explicit] QListWidgetItem::QListWidgetItem(QListWidget *parent = nullptr, int type = Type)

지정된 ` type `의 빈 리스트 위젯 항목을, 주어진 ` parent`을 사용하여 생성합니다. ` parent `이 지정되지 않은 경우, 해당 항목은 ` QListWidget::insertItem()`을 사용하여 리스트 위젯에 삽입되어야 합니다.

이 생성자는 항목을 생성자에 전달된 부모의 모델에 삽입합니다. 모델이 정렬된 경우, 모델이 항목에 대해 '<' 연산자 메서드를 호출하게 되는데, 이 시점에서 항목은 아직 생성되지 않았으므로 삽입 동작이 불확실해집니다. 이러한 불확실한 동작을 피하려면 부모를 지정하지 말고 대신 QListWidget::insertItem()을 사용하는 것이 좋습니다.

type()도 참조하십시오 .

[explicit] QListWidgetItem::QListWidgetItem(const QString &text, QListWidget *parent = nullptr, int type = Type)

지정된 ` type `의 빈 리스트 위젯 항목을, 주어진 ` text ` 및 ` parent`을 사용하여 생성합니다. 부모가 지정되지 않은 경우, 해당 항목은 ` QListWidget::insertItem()`을 사용하여 리스트 위젯에 삽입되어야 합니다.

이 생성자는 생성자에 전달된 부모의 모델에 항목을 삽입합니다. 모델이 정렬되어 있는 경우, 모델이 항목에 대해 '<' 연산자 메서드를 호출하게 되는데, 이 시점에서는 항목이 아직 생성되지 않았기 때문에 삽입 동작이 불확실해집니다. 이러한 불확실한 동작을 피하려면 부모를 지정하지 말고 대신 QListWidget::insertItem()을 사용하는 것이 좋습니다.

type()도 참조하십시오 .

[explicit] QListWidgetItem::QListWidgetItem(const QIcon &icon, const QString &text, QListWidget *parent = nullptr, int type = Type)

지정된 ` type `의 빈 리스트 위젯 항목을, 주어진 ` icon`, ` text ` 및 ` parent`을 사용하여 생성합니다. 부모가 지정되지 않은 경우, 해당 항목은 ` QListWidget::insertItem()`을 사용하여 리스트 위젯에 삽입되어야 합니다.

이 생성자는 항목을 생성자에 전달된 부모의 모델에 삽입합니다. 모델이 정렬된 상태라면, 모델이 항목에 대해 '<' 연산자 메서드를 호출하게 되는데, 이 시점에서 항목은 아직 생성되지 않았기 때문에 삽입 동작은 정의되지 않습니다. 이러한 정의되지 않은 동작을 피하려면 부모를 지정하지 말고 대신 QListWidget::insertItem()을 사용하는 것이 좋습니다.

type()도 참조하십시오 .

QListWidgetItem::QListWidgetItem(const QListWidgetItem &other)

other 의 복사본을 생성합니다. type()와 listWidget()는 복사되지 않는다는 점에 유의하십시오.

이 함수는 clone()을 재구현할 때 유용합니다.

data() 및 flags()도 참조하십시오 .

[virtual noexcept] QListWidgetItem::~QListWidgetItem()

목록 항목을 삭제합니다.

QBrush QListWidgetItem::background() const

목록 항목의 배경을 표시하는 데 사용된 브러시를 반환합니다.

setBackground() 및 foreground()도 참조하십시오 .

Qt::CheckState QListWidgetItem::checkState() const

목록 항목의 선택 상태를 반환합니다( Qt::CheckState 참조).

setCheckState() 및 flags()도 참조하십시오 .

[virtual] QListWidgetItem *QListWidgetItem::clone() const

항목의 정확한 복사본을 만듭니다.

[virtual] QVariant QListWidgetItem::data(int role) const

지정된 role 에 대한 항목의 데이터를 반환합니다. 추가적인 역할이나 특정 역할에 대한 특수한 동작이 필요한 경우 이 함수를 재구현하십시오.

Qt::ItemDataRole 및 setData()도 참조하십시오 .

Qt::ItemFlags QListWidgetItem::flags() const

이 항목에 대한 항목 플래그를 반환합니다( Qt::ItemFlags 참조).

setFlags()도 참조하십시오 .

QFont QListWidgetItem::font() const

이 목록 항목의 텍스트를 표시하는 데 사용된 글꼴을 반환합니다.

setFont()도 참조하십시오 .

QBrush QListWidgetItem::foreground() const

목록 항목의 전경(예: 텍스트)을 표시하는 데 사용되는 브러시를 반환합니다.

setForeground() 및 background()도 참조하십시오 .

QIcon QListWidgetItem::icon() const

목록 항목의 아이콘을 반환합니다.

setIcon() 및 iconSize도 참조하십시오 .

bool QListWidgetItem::isHidden() const

항목이 숨겨져 있으면 true 를 반환하고, 그렇지 않으면 false 를 반환합니다.

setHidden()도 참조하십시오 .

bool QListWidgetItem::isSelected() const

항목이 선택된 경우 true 를 반환하고, 그렇지 않은 경우 false 를 반환합니다.

setSelected()도 참조하십시오 .

QListWidget *QListWidgetItem::listWidget() const

해당 항목을 포함하는 목록 위젯을 반환합니다.

[virtual] void QListWidgetItem::read(QDataStream &in)

in 스트림에서 항목을 읽습니다.

write()도 참조하십시오 .

void QListWidgetItem::setBackground(const QBrush &brush)

목록 항목의 배경 브러시를 지정된 brush 로 설정합니다. 기본 생성된 브러시를 설정하면 뷰에서 스타일의 기본 색상을 사용하게 됩니다.

background() 및 setForeground()도 참조하십시오 .

void QListWidgetItem::setCheckState(Qt::CheckState state)

목록 항목의 선택 상태를 ‘ state ’로 설정합니다.

checkState()도 참조하십시오 .

[virtual] void QListWidgetItem::setData(int role, const QVariant &value)

지정된 role 의 데이터를 지정된 value 으로 설정합니다. 특정 역할에 대해 추가적인 역할이나 특별한 동작이 필요한 경우 이 함수를 재구현하십시오.

참고: 기본구현에서는 ` Qt::EditRole `와 ` Qt::DisplayRole `가 동일한 데이터를 가리키는 것으로 간주합니다.

Qt::ItemDataRole 및 data()도 참조하십시오 .

void QListWidgetItem::setFlags(Qt::ItemFlags flags)

목록 항목의 항목 플래그를 flags 로 설정합니다.

flags() 및 Qt::ItemFlags도 참조하십시오 .

void QListWidgetItem::setFont(const QFont &font)

항목을 그릴 때 사용되는 글꼴을 지정된 ` font`로 설정합니다.

font()도 참조하십시오 .

void QListWidgetItem::setForeground(const QBrush &brush)

목록 항목의 전경 브러시를 지정된 ` brush`로 설정합니다. 기본 생성된 브러시를 설정하면 뷰에서 스타일의 기본 색상을 사용하게 됩니다.

foreground() 및 setBackground()도 참조하십시오 .

void QListWidgetItem::setHidden(bool hide)

hide 가 true인 경우 항목을 숨기고, 그렇지 않은 경우 항목을 표시합니다.

isHidden()도 참조하십시오 .

void QListWidgetItem::setIcon(const QIcon &icon)

목록 항목의 아이콘을 지정된 icon 로 설정합니다.

icon(), text() 및 iconSize도 참조하십시오 .

void QListWidgetItem::setSelected(bool select)

항목의 선택 상태를 ‘ select ’으로 설정합니다.

isSelected()도 참조하십시오 .

void QListWidgetItem::setSizeHint(const QSize &size)

목록 항목의 크기 힌트를 size 로 설정합니다. 크기 힌트가 설정되지 않았거나 size 가 유효하지 않은 경우, 항목 델리게이트가 항목 데이터를 기반으로 크기 힌트를 계산합니다.

sizeHint()도 참조하십시오 .

void QListWidgetItem::setStatusTip(const QString &statusTip)

목록 항목의 상태 툴팁을 statusTip 에서 지정한 텍스트로 설정합니다. QListWidget 이 기능을 사용하려면 mouseTracking이 활성화되어 있어야 합니다.

statusTip(), setToolTip(), setWhatsThis() 및 QWidget::setMouseTracking()도 참조하십시오 .

void QListWidgetItem::setText(const QString &text)

목록 위젯 항목의 텍스트를 지정된 ` text`으로 설정합니다.

text()도 참조하십시오 .

[since 6.4] void QListWidgetItem::setTextAlignment(Qt::Alignment alignment)

목록 항목의 텍스트 정렬을 ‘ alignment ’로 설정합니다.

이 함수는 Qt 6.4에서 도입되었습니다.

textAlignment()도 참조하십시오 .

void QListWidgetItem::setToolTip(const QString &toolTip)

목록 항목의 툴팁을 toolTip 에서 지정한 텍스트로 설정합니다.

toolTip(), setStatusTip() 및 setWhatsThis()도 참조하십시오 .

void QListWidgetItem::setWhatsThis(const QString &whatsThis)

목록 항목에 대한 “이게 뭐죠?” 도움말 내용을 whatsThis 에서 지정한 텍스트로 설정합니다.

whatsThis(), setStatusTip() 및 setToolTip()도 참조하십시오 .

QSize QListWidgetItem::sizeHint() const

목록 항목에 설정된 크기 힌트를 반환합니다.

setSizeHint()도 참조하십시오 .

QString QListWidgetItem::statusTip() const

목록 항목의 상태 툴팁을 반환합니다.

setStatusTip()도 참조하십시오 .

QString QListWidgetItem::text() const

목록 항목의 텍스트를 반환합니다.

setText()도 참조하십시오 .

int QListWidgetItem::textAlignment() const

목록 항목의 텍스트 정렬 방식을 반환합니다.

참고: 이 함수는 역사적인 이유로 int형을 반환합니다. Qt 7에서는 Qt::Alignment 를 반환하도록 수정될 예정입니다.

setTextAlignment() 및 Qt::Alignment도 참조하십시오 .

QString QListWidgetItem::toolTip() const

목록 항목의 툴팁을 반환합니다.

setToolTip(), statusTip(), whatsThis()도 참조하십시오 .

int QListWidgetItem::type() const

QListWidgetItem 생성자에 전달된 타입을 반환합니다.

QString QListWidgetItem::whatsThis() const

목록 항목의 “이게 뭐죠?” 도움말 텍스트를 반환합니다.

setWhatsThis(), statusTip() 및 toolTip()도 참조하십시오 .

[virtual] void QListWidgetItem::write(QDataStream &out) const

항목을 out 스트림에 기록합니다.

read()도 참조하십시오 .

[virtual] bool QListWidgetItem::operator<(const QListWidgetItem &other) const

이 항목의 텍스트가 other 항목의 텍스트보다 짧으면 true 를 반환하고, 그렇지 않으면 false 를 반환합니다.

QListWidgetItem &QListWidgetItem::operator=(const QListWidgetItem &other)

other 의 데이터와 플래그를 이 항목에 할당합니다. 단, type() 및 listWidget()는 복사되지 않는다는 점에 유의하십시오.

이 함수는 ` clone()`를 재구현할 때 유용합니다.

data() 및 flags()도 참조하십시오 .

관련 비멤버

QDataStream &operator<<(QDataStream &out, const QListWidgetItem &item)

item 목록 위젯 항목을 out 스트림에 기록합니다.

이 연산자는 QListWidgetItem::write()을 사용합니다.

Qt 데이터 유형의 직렬화항목도 참조하십시오 .

QDataStream &operator>>(QDataStream &in, QListWidgetItem &item)

in 스트림에서 리스트 위젯 항목을 읽어와 item 에 저장합니다.

이 연산자는 QListWidgetItem::read()을 사용합니다.

Qt 데이터 유형의 직렬화항목도 참조하십시오 .

© 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.