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 의 단일 항목을 나타냅니다. 각 항목은 여러 가지 정보를 담을 수 있으며 적절하게 표시합니다.

항목 보기 편의 클래스는 순수한 모델/보기 접근 방식이 아닌 고전적인 항목 기반 인터페이스를 사용합니다. 보다 유연한 목록 보기 위젯을 사용하려면 표준 모델과 함께 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

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

Constant설명
QListWidgetItem::Type0목록 위젯 항목의 기본 유형입니다.
QListWidgetItem::UserType1000사용자 정의 유형에 대한 최소값입니다. UserType 이하의 값은 Qt에 의해 예약되어 있습니다.

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

type()도 참조하세요 .

멤버 함수 문서

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

지정된 parent 을 사용하여 지정된 type 의 빈 목록 위젯 항목을 생성합니다. parent 을 지정하지 않으면 QListWidget::insertItem()을 사용하여 목록 위젯에 항목을 삽입해야 합니다.

이 생성자는 생성자에게 전달된 부모의 모델에 항목을 삽입합니다. 모델이 정렬되면 이 시점에서 아직 구성되지 않은 항목에 대해 '<' 연산자 메서드를 호출하므로 삽입의 동작이 결정되지 않습니다. 결정되지 않은 동작을 방지하려면 부모를 지정하지 않고 QListWidget::insertItem()를 대신 사용하는 것이 좋습니다.

type()도 참조하세요 .

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

지정된 textparent 을 사용하여 지정된 type 의 빈 목록 위젯 항목을 생성합니다. 부모가 지정되지 않은 경우 항목은 QListWidget::insertItem()을 사용하여 목록 위젯에 삽입해야 합니다.

이 생성자는 생성자에게 전달된 부모의 모델에 항목을 삽입합니다. 모델이 정렬되면 이 시점에서 아직 구성되지 않은 항목에 대해 '<' 연산자 메서드를 호출하므로 삽입의 동작이 결정되지 않습니다. 결정되지 않은 동작을 방지하려면 부모를 지정하지 않고 QListWidget::insertItem()를 대신 사용하는 것이 좋습니다.

type()도 참조하세요 .

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

지정된 icon, textparent 을 사용하여 지정된 type 의 빈 목록 위젯 항목을 생성합니다. 부모가 지정되지 않은 경우 항목은 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::ItemDataRolesetData()도 참조하세요 .

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::EditRoleQt::DisplayRole 을 동일한 데이터를 참조하는 것으로 취급합니다.

Qt::ItemDataRoledata()도 참조하세요 .

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 이 참이면 항목을 숨기고, 그렇지 않으면 항목을 표시합니다.

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 마우스 추적을 활성화해야 이 기능이 작동합니다.

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

목록 항목의 텍스트 맞춤을 반환합니다.

참고: 이 함수는 기록상의 이유로 정수를 반환합니다. 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 데이터 형 직렬화도참조하십시오 .

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