QListView Class

QListView 클래스는 모델에 목록 또는 아이콘 보기를 제공합니다. 더 보기...

Header: #include <QListView>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
상속합니다: QAbstractItemView
상속받습니다:

QHelpIndexWidget, QListWidget, 그리고 QUndoView

공용 유형

enum Flow { LeftToRight, TopToBottom }
enum LayoutMode { SinglePass, Batched }
enum Movement { Static, Free, Snap }
enum ResizeMode { Fixed, Adjust }
enum ViewMode { ListMode, IconMode }

속성

공용 함수

QListView(QWidget *parent = nullptr)
virtual ~QListView()
int batchSize() const
void clearPropertyFlags()
QListView::Flow flow() const
QSize gridSize() const
bool isRowHidden(int row) const
bool isSelectionRectVisible() const
bool isWrapping() const
Qt::Alignment itemAlignment() const
QListView::LayoutMode layoutMode() const
int modelColumn() const
QListView::Movement movement() const
QListView::ResizeMode resizeMode() const
void setBatchSize(int batchSize)
void setFlow(QListView::Flow flow)
void setGridSize(const QSize &size)
void setItemAlignment(Qt::Alignment alignment)
void setLayoutMode(QListView::LayoutMode mode)
void setModelColumn(int column)
void setMovement(QListView::Movement movement)
void setResizeMode(QListView::ResizeMode mode)
void setRowHidden(int row, bool hide)
void setSelectionRectVisible(bool show)
void setSpacing(int space)
void setUniformItemSizes(bool enable)
void setViewMode(QListView::ViewMode mode)
void setWordWrap(bool on)
void setWrapping(bool enable)
int spacing() const
bool uniformItemSizes() const
QListView::ViewMode viewMode() const
bool wordWrap() const

재구현된 공용 함수

virtual QModelIndex indexAt(const QPoint &p) const override
virtual void scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible) override
virtual void setRootIndex(const QModelIndex &index) override
virtual QRect visualRect(const QModelIndex &index) const override

신호

void indexesMoved(const QModelIndexList &indexes)

보호된 함수

QRect rectForIndex(const QModelIndex &index) const
void setPositionForIndex(const QPoint &position, const QModelIndex &index)

재구현된 보호 함수

virtual void currentChanged(const QModelIndex &current, const QModelIndex &previous) override
virtual void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>()) override
virtual void dragLeaveEvent(QDragLeaveEvent *e) override
virtual void dragMoveEvent(QDragMoveEvent *e) override
virtual void dropEvent(QDropEvent *event) override
virtual bool event(QEvent *e) override
virtual int horizontalOffset() const override
virtual void initViewItemOption(QStyleOptionViewItem *option) const override
virtual bool isIndexHidden(const QModelIndex &index) const override
virtual void mouseMoveEvent(QMouseEvent *e) override
virtual void mouseReleaseEvent(QMouseEvent *e) override
virtual QModelIndex moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers) override
virtual void paintEvent(QPaintEvent *e) override
virtual void resizeEvent(QResizeEvent *e) override
virtual void rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end) override
virtual void rowsInserted(const QModelIndex &parent, int start, int end) override
virtual void scrollContentsBy(int dx, int dy) override
virtual QModelIndexList selectedIndexes() const override
virtual void selectionChanged(const QItemSelection &selected, const QItemSelection &deselected) override
virtual void setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command) override
virtual void startDrag(Qt::DropActions supportedActions) override
virtual void timerEvent(QTimerEvent *e) override
virtual void updateGeometries() override
virtual int verticalOffset() const override
virtual QSize viewportSizeHint() const override
virtual QRegion visualRegionForSelection(const QItemSelection &selection) const override
virtual void wheelEvent(QWheelEvent *e) override

상세 설명

QListView는 모델에 저장된 항목을 단순한 비계층적 목록 또는 아이콘 모음으로 표시합니다. 이 클래스는 이전에 QListBoxQIconView 클래스에서 제공했던 목록과 아이콘 뷰를 제공하는 데 사용되지만, Qt의 모델/뷰 아키텍처가 제공하는 보다 유연한 접근 방식을 사용합니다.

QListView 클래스는 모델/뷰 클래스 중 하나이며 Qt의 모델/뷰 프레임워크의 일부입니다.

이 뷰는 가로 또는 세로 헤더를 표시하지 않습니다. 가로 헤더가 있는 항목 목록을 표시하려면 QTreeView 를 대신 사용합니다.

QListView는 QAbstractItemView 클래스에 정의된 인터페이스를 구현하여 QAbstractItemModel 클래스에서 파생된 모델에서 제공하는 데이터를 표시할 수 있습니다.

목록 보기의 항목은 두 가지 보기 모드 중 하나를 사용하여 표시할 수 있습니다: ListMode 에서는 항목이 단순한 목록의 형태로 표시되고, IconMode 에서는 항목이 파일 관리자의 파일처럼 아이콘으로 표시되는 아이콘 보기의 형태를 취합니다. 기본적으로 목록 보기는 ListMode 에 있습니다. 보기 모드를 변경하려면 setViewMode() 함수를 사용하고, 현재 보기 모드를 확인하려면 viewMode()을 사용합니다.

이 보기의 항목은 목록 보기의 flow()에서 지정한 방향으로 배치됩니다. 뷰의 movement() 상태에 따라 항목이 제자리에 고정되거나 이동이 허용될 수 있습니다.

모델의 항목을 흐름 방향으로 완전히 배치할 수 없는 경우 뷰 위젯의 경계에서 래핑할 수 있으며, 이는 isWrapping()에 따라 달라집니다. 이 속성은 항목이 아이콘 보기로 표시될 때 유용합니다.

resizeMode() 및 layoutMode()은 항목이 배치되는 방법과 시기를 결정합니다. 항목은 spacing()에 따라 간격이 지정되며 gridSize()로 지정된 크기의 개념적 그리드 내에 존재할 수 있습니다. 항목은 iconSize()에 따라 크거나 작은 아이콘으로 렌더링될 수 있습니다.

성능 개선

많은 수의 항목을 표시할 때 성능을 개선하기 위해 뷰에 처리 중인 데이터에 대한 힌트를 제공할 수 있습니다. 크기가 동일한 항목을 표시하려는 뷰에 대해 취할 수 있는 한 가지 접근 방식은 uniformItemSizes 속성을 true로 설정하는 것입니다.

뷰 클래스, QTreeView, QTableView, 및 QListWidget참조하십시오 .

멤버 유형 문서

enum QListView::Flow

상수설명
QListView::LeftToRight0항목은 왼쪽에서 오른쪽으로 보기에 배치됩니다.
QListView::TopToBottom1항목은 뷰에서 위에서 아래로 배치됩니다.

enum QListView::LayoutMode

상수설명
QListView::SinglePass0항목이 한꺼번에 배치됩니다.
QListView::Batched1항목은 batchSize 항목의 일괄 배치로 배치됩니다.

batchSize참조하세요 .

enum QListView::Movement

상수설명
QListView::Static0사용자가 항목을 이동할 수 없습니다.
QListView::Free1항목은 사용자가 자유롭게 이동할 수 있습니다.
QListView::Snap2항목은 이동 시 지정된 그리드에 스냅됩니다( setGridSize() 참조).

enum QListView::ResizeMode

상수설명
QListView::Fixed0뷰를 처음 표시할 때만 항목이 배치됩니다.
QListView::Adjust1뷰의 크기를 조정할 때마다 항목이 배치됩니다.

enum QListView::ViewMode

상수설명
QListView::ListMode0아이템은 TopToBottom 플로우를 사용하여 작은 크기와 정적 이동으로 배치됩니다.
QListView::IconMode1아이템은 LeftToRight 플로우를 사용하여 배치되며, 큰 크기와 자유로운 움직임이 있습니다.

프로퍼티 문서

batchSize : int

이 속성은 layoutModeBatched 으로 설정된 경우 각 배치에 배치된 항목 수를 보유합니다.

기본값은 100입니다.

액세스 함수:

int batchSize() const
void setBatchSize(int batchSize)

flow : Flow

이 속성은 항목 레이아웃이 흐르는 방향을 지정합니다.

이 속성이 LeftToRight 인 경우 항목이 왼쪽에서 오른쪽으로 배치됩니다. isWrapping 속성이 true 인 경우 표시 영역의 오른쪽에 도달하면 레이아웃이 래핑됩니다. 이 속성이 TopToBottom 인 경우 항목은 보이는 영역의 위쪽부터 배치되며 아래쪽에 도달하면 래핑됩니다.

뷰가 표시될 때 이 속성을 설정하면 항목이 다시 배치됩니다.

기본적으로 이 속성은 TopToBottom 으로 설정됩니다.

함수에 액세스합니다:

QListView::Flow flow() const
void setFlow(QListView::Flow flow)

viewMode참조하세요 .

gridSize : QSize

이 속성은 레이아웃 그리드의 크기를 보유합니다.

이 속성은 항목이 레이아웃되는 그리드의 크기입니다. 기본값은 비어 있는 크기이며, 이는 그리드가 없고 레이아웃이 그리드에서 수행되지 않음을 의미합니다. 이 속성을 비어 있지 않은 크기로 설정하면 그리드 레이아웃이 켜집니다. (그리드 레이아웃이 적용되면 spacing 속성은 무시됩니다.)

보기가 표시될 때 이 속성을 설정하면 항목이 다시 레이아웃됩니다.

기능에 접근합니다:

QSize gridSize() const
void setGridSize(const QSize &size)

viewMode참조하세요 .

isWrapping : bool

이 속성은 항목 레이아웃을 줄 바꿈할지 여부를 저장합니다.

이 속성은 표시 영역에 더 이상 공간이 없을 때 레이아웃을 줄 바꿈할지 여부를 보유합니다. 레이아웃이 래핑되는 지점은 flow 속성에 따라 달라집니다.

뷰가 표시될 때 이 속성을 설정하면 항목이 다시 배치됩니다.

기본적으로 이 속성은 false 입니다.

함수에 액세스합니다:

bool isWrapping() const
void setWrapping(bool enable)

viewMode참조하세요 .

itemAlignment : Qt::Alignment

이 속성은 셀에 있는 각 항목의 정렬을 유지합니다.

이 속성은 TopToBottom 흐름이 있고 래핑이 활성화된 ListMode 에서만 지원됩니다. 기본 맞춤은 0으로, 항목이 해당 셀을 완전히 채우는 것을 의미합니다.

함수 액세스:

Qt::Alignment itemAlignment() const
void setItemAlignment(Qt::Alignment alignment)

layoutMode : LayoutMode

는 항목의 레이아웃을 즉시 수행할지 아니면 지연시킬지 여부를 결정합니다.

이 속성은 항목의 레이아웃 모드를 보유합니다. 모드가 SinglePass (기본값)이면 항목이 한 번에 모두 레이아웃됩니다. 모드가 Batched 인 경우 항목은 이벤트를 처리하는 동안 batchSize 항목의 일괄 배치로 레이아웃됩니다. 이렇게 하면 나머지 항목이 배치되는 동안 표시되는 항목을 즉시 보고 상호 작용할 수 있습니다.

기능에 액세스합니다:

QListView::LayoutMode layoutMode() const
void setLayoutMode(QListView::LayoutMode mode)

viewMode참조하세요 .

modelColumn : int

이 속성은 모델에서 표시되는 열을 보유합니다.

기본적으로 이 속성은 0을 포함하며, 이는 모델의 첫 번째 열이 표시됨을 나타냅니다.

함수 액세스:

int modelColumn() const
void setModelColumn(int column)

movement : Movement

이 속성은 항목을 자유롭게 이동할 수 있는지, 그리드에 고정되어 있는지 또는 전혀 이동할 수 없는지를 나타냅니다.

Static 은 사용자가 항목을 이동할 수 없음을 의미합니다. Free 은 사용자가 항목을 뷰의 모든 위치로 끌어 놓을 수 있음을 의미합니다. Snap 은 사용자가 항목을 끌어 놓을 수 있지만 gridSize 속성으로 표시된 개념적 격자의 위치로만 끌어 놓을 수 있음을 의미합니다.

뷰가 표시될 때 이 속성을 설정하면 항목이 다시 배치됩니다.

기본적으로 이 속성은 Static 로 설정되어 있습니다.

함수에 액세스합니다:

QListView::Movement movement() const
void setMovement(QListView::Movement movement)

gridSize, resizeMode, viewMode참조하세요 .

resizeMode : ResizeMode

이 속성은 뷰의 크기를 조정할 때 항목이 다시 배치되는지 여부를 저장합니다.

이 속성이 Adjust 인 경우 뷰의 크기를 조정할 때 항목이 다시 배치됩니다. 값이 Fixed 인 경우 뷰의 크기를 조정할 때 항목이 다시 배치되지 않습니다.

기본적으로 이 속성은 Fixed 으로 설정됩니다.

함수에 액세스합니다:

QListView::ResizeMode resizeMode() const
void setResizeMode(QListView::ResizeMode mode)

movement, gridSizeviewMode참조하십시오 .

selectionRectVisible : bool

선택 사각형이 표시되어야 하는 경우

이 속성이 true 이면 선택 사각형이 표시되고, 그렇지 않으면 선택 사각형이 숨겨집니다.

참고: 선택 사각형은 선택 모드가 두 개 이상의 항목을 선택할 수 있는 모드인 경우에만 표시됩니다. 즉, 선택 모드가 QAbstractItemView::SingleSelection 인 경우 선택 사각형이 그려지지 않습니다.

기본적으로 이 속성은 false 입니다.

기능에 접근합니다:

bool isSelectionRectVisible() const
void setSelectionRectVisible(bool show)

spacing : int

이 속성은 레이아웃에서 항목 주위의 공간을 보유합니다.

이 속성은 레이아웃에서 항목 주위에 채워지는 빈 공간의 크기입니다.

뷰가 표시될 때 이 속성을 설정하면 항목이 다시 배치됩니다.

기본적으로 이 속성의 값은 0입니다.

함수에 액세스합니다:

int spacing() const
void setSpacing(int space)

viewMode참조하세요 .

uniformItemSizes : bool

이 속성은 목록 뷰의 모든 항목의 크기가 동일한지 여부를 유지합니다.

이 속성은 뷰의 모든 항목의 크기가 동일한 것이 보장되는 경우에만 true로 설정해야 합니다. 이렇게 하면 뷰에서 성능 목적으로 일부 최적화를 수행할 수 있습니다.

기본적으로 이 속성은 false 입니다.

액세스 함수:

bool uniformItemSizes() const
void setUniformItemSizes(bool enable)

viewMode : ViewMode

이 속성은 QListView 의 보기 모드를 보유합니다.

이 속성은 설정되지 않은 다른 속성을 설정된 보기 모드에 맞게 변경합니다. QListView 이미 설정된 -특정 속성은 clearPropertyFlags()가 호출되지 않는 한 변경되지 않습니다.

보기 모드를 설정하면 선택한 이동에 따라 드래그 앤 드롭이 활성화 또는 비활성화됩니다. ListMode 의 경우 기본 이동은 Static (드래그 앤 드롭 비활성화)이고, IconMode 의 경우 기본 이동은 Free (드래그 앤 드롭 활성화)입니다.

기능에 액세스합니다:

QListView::ViewMode viewMode() const
void setViewMode(QListView::ViewMode mode)

isWrapping, spacing, gridSize, flow, movement, resizeMode참조하세요 .

wordWrap : bool

이 속성은 항목 텍스트 단어 줄 바꿈 정책을 보유합니다.

이 속성이 true 인 경우 항목 텍스트는 단어 나누기에서 필요한 곳에 줄 바꿈되고, 그렇지 않으면 전혀 줄 바꿈되지 않습니다. 이 속성은 기본적으로 false 입니다.

줄 바꿈이 활성화되어 있어도 텍스트를 위한 공간을 확보하기 위해 셀이 확장되지는 않습니다. 뷰의 textElideMode 에 따라 표시할 수 없는 텍스트에는 줄임표가 인쇄됩니다.

액세스 함수:

bool wordWrap() const
void setWordWrap(bool on)

멤버 함수 문서

[explicit] QListView::QListView(QWidget *parent = nullptr)

모델을 보기 위해 주어진 parent 으로 새 QListView를 만듭니다. setModel ()를 사용하여 모델을 설정합니다.

[virtual noexcept] QListView::~QListView()

보기를 파괴합니다.

void QListView::clearPropertyFlags()

QListView-특정 속성 플래그를 지웁니다. viewMode 을 참조하세요.

QAbstractItemView 에서 상속된 속성은 속성 플래그가 적용되지 않습니다. 특히 dragEnabledacceptsDropssetMovement() 또는 setViewMode()를 호출할 때 QListView 에 의해 계산됩니다.

[override virtual protected] void QListView::currentChanged(const QModelIndex &current, const QModelIndex &previous)

재구현합니다: QAbstractItemView::currentChanged(const QModelIndex &current, const QModelIndex &previous).

[override virtual protected] void QListView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles = QList<int>())

재구현합니다: QAbstractItemView::dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight, const QList<int> &roles).

[override virtual protected] void QListView::dragLeaveEvent(QDragLeaveEvent *e)

다시 구현합니다: QAbstractItemView::dragLeaveEvent(QDragLeaveEvent * 이벤트).

[override virtual protected] void QListView::dragMoveEvent(QDragMoveEvent *e)

다시 구현합니다: QAbstractItemView::dragMoveEvent(QDragMoveEvent * 이벤트).

[override virtual protected] void QListView::dropEvent(QDropEvent *event)

다시 구현합니다: QAbstractItemView::dropEvent(QDropEvent * 이벤트).

[override virtual protected] bool QListView::event(QEvent *e)

다시 구현합니다: QAbstractItemView::event(QEvent * 이벤트).

[override virtual protected] int QListView::horizontalOffset() const

재구현합니다: QAbstractItemView::horizontalOffset() const.

[override virtual] QModelIndex QListView::indexAt(const QPoint &p) const

재구현합니다: QAbstractItemView::indexAt(const QPoint &point) const.

[signal] void QListView::indexesMoved(const QModelIndexList &indexes)

이 신호는 뷰에서 지정된 indexes 을 이동할 때 발생합니다.

[override virtual protected] void QListView::initViewItemOption(QStyleOptionViewItem *option) const

재구현합니다: QAbstractItemView::initViewItemOption(Q스타일옵션뷰아이템 *옵션) const.

[override virtual protected] bool QListView::isIndexHidden(const QModelIndex &index) const

재구현합니다: QAbstractItemView::isIndexHidden(const QModelIndex &index) const.

bool QListView::isRowHidden(int row) const

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

[override virtual protected] void QListView::mouseMoveEvent(QMouseEvent *e)

다시 구현합니다: QAbstractItemView::mouseMoveEvent(QMouseEvent * 이벤트).

[override virtual protected] void QListView::mouseReleaseEvent(QMouseEvent *e)

다시 구현합니다: QAbstractItemView::mouseReleaseEvent(QMouseEvent * 이벤트).

[override virtual protected] QModelIndex QListView::moveCursor(QAbstractItemView::CursorAction cursorAction, Qt::KeyboardModifiers modifiers)

재구현합니다: QAbstractItemView::moveCursor(QAbstractItemView::커서 액션 커서 액션, Qt::키보드 모디파이어 수정자).

[override virtual protected] void QListView::paintEvent(QPaintEvent *e)

다시 구현합니다: QAbstractScrollArea::paintEvent(QPaintEvent * 이벤트).

[protected] QRect QListView::rectForIndex(const QModelIndex &index) const

모델에서 index 위치에 있는 항목의 직사각형을 반환합니다. 직사각형은 콘텐츠 좌표입니다.

visualRect()도 참조하세요 .

[override virtual protected] void QListView::resizeEvent(QResizeEvent *e)

다시 구현합니다: QAbstractItemView::resizeEvent(QResizeEvent * 이벤트).

[override virtual protected] void QListView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end)

재구현합니다: QAbstractItemView::rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end).

[override virtual protected] void QListView::rowsInserted(const QModelIndex &parent, int start, int end)

재구현합니다: QAbstractItemView::rowsInserted(const QModelIndex &parent, int start, int end).

[override virtual protected] void QListView::scrollContentsBy(int dx, int dy)

재구현합니다: QAbstractScrollArea::scrollContentsBy(int dx, int dy).

dxdy 으로 뷰 콘텐츠를 스크롤합니다.

[override virtual] void QListView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint hint = EnsureVisible)

재구현합니다: QAbstractItemView::scrollTo(const QModelIndex &index, QAbstractItemView::ScrollHint 힌트).

[override virtual protected] QModelIndexList QListView::selectedIndexes() const

재구현합니다: QAbstractItemView::selectedIndexes() const.

[override virtual protected] void QListView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected)

재구현합니다: QAbstractItemView::selectionChanged(const QItemSelection &selected, const QItemSelection &deselected).

[protected] void QListView::setPositionForIndex(const QPoint &position, const QModelIndex &index)

모델에서 index 에 있는 항목의 콘텐츠 위치를 지정된 position 으로 설정합니다. 목록 보기의 이동 모드가 정적이거나 보기 모드가 ListView 인 경우에는 이 함수가 적용되지 않습니다.

[override virtual] void QListView::setRootIndex(const QModelIndex &index)

재구현합니다: QAbstractItemView::setRootIndex(const QModelIndex &index).

void QListView::setRowHidden(int row, bool hide)

hide 이 참이면 지정된 row 이 숨겨지고, 그렇지 않으면 row 이 표시됩니다.

isRowHidden()도 참조하세요 .

[override virtual protected] void QListView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command)

재구현합니다: QAbstractItemView::setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags 플래그).

[override virtual protected] void QListView::startDrag(Qt::DropActions supportedActions)

다시 구현합니다: QAbstractItemView::startDrag(Qt::DropActions supportedActions).

[override virtual protected] void QListView::timerEvent(QTimerEvent *e)

다시 구현합니다: QAbstractItemView::timerEvent(Q타이머이벤트 *이벤트).

[override virtual protected] void QListView::updateGeometries()

다시 구현합니다: QAbstractItemView::updateGeometries().

[override virtual protected] int QListView::verticalOffset() const

재구현합니다: QAbstractItemView::verticalOffset() const.

[override virtual protected] QSize QListView::viewportSizeHint() const

재구현합니다: QAbstractItemView::viewportSizeHint() const.

[override virtual] QRect QListView::visualRect(const QModelIndex &index) const

재구현합니다: QAbstractItemView::visualRect(const QModelIndex &index) const.

[override virtual protected] QRegion QListView::visualRegionForSelection(const QItemSelection &selection) const

재구현합니다: QAbstractItemView::visualRegionForSelection(const QItemSelection &selection) const.

4.7부터 반환되는 영역에는 뷰포트와 교차하는(또는 뷰포트에 포함된) 직사각형만 포함됩니다.

[override virtual protected] void QListView::wheelEvent(QWheelEvent *e)

다시 구현합니다: QAbstractScrollArea::wheelEvent(QWheelEvent *e).

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