include/QtWidgets/qabstractitemview.h

0001 // Copyright (C) 2016 The Qt Company Ltd.
0002 // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
0003 // Qt-Security score:significant reason:default
0004
0005 #ifndef QABSTRACTITEMVIEW_H
0006 #define QABSTRACTITEMVIEW_H
0007
0008 #include <QtWidgets/qtwidgetsglobal.h>
0009 #include <QtWidgets/qabstractscrollarea.h>
0010 #include <QtCore/qabstractitemmodel.h>
0011 #include <QtCore/qitemselectionmodel.h>
0012 #include <QtWidgets/qabstractitemdelegate.h>
0013
0014 class tst_QAbstractItemView;
0015 class tst_QTreeView;
0016
0017 QT_REQUIRE_CONFIG(itemviews);
0018
0019 QT_BEGIN_NAMESPACE
0020
0021 class QMenu;
0022 class QDrag;
0023 class QEvent;
0024 class QAbstractItemViewPrivate;
0025
0026 class Q_WIDGETS_EXPORT QAbstractItemView : public QAbstractScrollArea
0027 {
0028     Q_OBJECT
0029     Q_PROPERTY(bool autoScroll READ hasAutoScroll WRITE setAutoScroll)
0030     Q_PROPERTY(int autoScrollMargin READ autoScrollMargin WRITE setAutoScrollMargin)
0031     Q_PROPERTY(EditTriggers editTriggers READ editTriggers WRITE setEditTriggers)
0032     Q_PROPERTY(bool tabKeyNavigation READ tabKeyNavigation WRITE setTabKeyNavigation)
0033 #if QT_CONFIG(draganddrop)
0034     Q_PROPERTY(bool showDropIndicator READ showDropIndicator WRITE setDropIndicatorShown)
0035     Q_PROPERTY(bool dragEnabled READ dragEnabled WRITE setDragEnabled)
0036     Q_PROPERTY(bool dragDropOverwriteMode READ dragDropOverwriteMode WRITE setDragDropOverwriteMode)
0037     Q_PROPERTY(DragDropMode dragDropMode READ dragDropMode WRITE setDragDropMode)
0038     Q_PROPERTY(Qt::DropAction defaultDropAction READ defaultDropAction WRITE setDefaultDropAction)
0039 #endif
0040     Q_PROPERTY(bool alternatingRowColors READ alternatingRowColors WRITE setAlternatingRowColors)
0041     Q_PROPERTY(SelectionMode selectionMode READ selectionMode WRITE setSelectionMode)
0042     Q_PROPERTY(SelectionBehavior selectionBehavior READ selectionBehavior
0043                WRITE setSelectionBehavior)
0044     Q_PROPERTY(QSize iconSize READ iconSize WRITE setIconSize NOTIFY iconSizeChanged)
0045     Q_PROPERTY(Qt::TextElideMode textElideMode READ textElideMode WRITE setTextElideMode)
0046     Q_PROPERTY(ScrollMode verticalScrollMode READ verticalScrollMode WRITE setVerticalScrollMode
0047                RESET resetVerticalScrollMode)
0048     Q_PROPERTY(ScrollMode horizontalScrollMode READ horizontalScrollMode
0049                WRITE setHorizontalScrollMode RESET resetHorizontalScrollMode)
0050     Q_PROPERTY(int updateThreshold READ updateThreshold WRITE setUpdateThreshold)
0051
0052 public:
0053     enum SelectionMode {
0054         NoSelection,
0055         SingleSelection,
0056         MultiSelection,
0057         ExtendedSelection,
0058         ContiguousSelection
0059     };
0060     Q_ENUM(SelectionMode)
0061
0062     enum SelectionBehavior {
0063         SelectItems,
0064         SelectRows,
0065         SelectColumns
0066     };
0067     Q_ENUM(SelectionBehavior)
0068
0069     enum ScrollHint {
0070         EnsureVisible,
0071         PositionAtTop,
0072         PositionAtBottom,
0073         PositionAtCenter
0074     };
0075     Q_ENUM(ScrollHint)
0076
0077     enum EditTrigger {
0078         NoEditTriggers = 0,
0079         CurrentChanged = 1,
0080         DoubleClicked = 2,
0081         SelectedClicked = 4,
0082         EditKeyPressed = 8,
0083         AnyKeyPressed = 16,
0084         AllEditTriggers = 31
0085     };
0086
0087     Q_DECLARE_FLAGS(EditTriggers, EditTrigger)
0088     Q_FLAG(EditTriggers)
0089
0090     enum ScrollMode {
0091         ScrollPerItem,
0092         ScrollPerPixel
0093     };
0094     Q_ENUM(ScrollMode)
0095
0096     explicit QAbstractItemView(QWidget *parent = nullptr);
0097     ~QAbstractItemView();
0098
0099     virtual void setModel(QAbstractItemModel *model);
0100     QAbstractItemModel *model() const;
0101
0102     virtual void setSelectionModel(QItemSelectionModel *selectionModel);
0103     QItemSelectionModel *selectionModel() const;
0104
0105     void setItemDelegate(QAbstractItemDelegate *delegate);
0106     QAbstractItemDelegate *itemDelegate() const;
0107
0108     void setSelectionMode(QAbstractItemView::SelectionMode mode);
0109     QAbstractItemView::SelectionMode selectionMode() const;
0110
0111     void setSelectionBehavior(QAbstractItemView::SelectionBehavior behavior);
0112     QAbstractItemView::SelectionBehavior selectionBehavior() const;
0113
0114     QModelIndex currentIndex() const;
0115     QModelIndex rootIndex() const;
0116
0117     void setEditTriggers(EditTriggers triggers);
0118     EditTriggers editTriggers() const;
0119
0120     void setVerticalScrollMode(ScrollMode mode);
0121     ScrollMode verticalScrollMode() const;
0122     void resetVerticalScrollMode();
0123
0124     void setHorizontalScrollMode(ScrollMode mode);
0125     ScrollMode horizontalScrollMode() const;
0126     void resetHorizontalScrollMode();
0127
0128     void setAutoScroll(bool enable);
0129     bool hasAutoScroll() const;
0130
0131     void setAutoScrollMargin(int margin);
0132     int autoScrollMargin() const;
0133
0134     void setTabKeyNavigation(bool enable);
0135     bool tabKeyNavigation() const;
0136
0137 #if QT_CONFIG(draganddrop)
0138     void setDropIndicatorShown(bool enable);
0139     bool showDropIndicator() const;
0140
0141     void setDragEnabled(bool enable);
0142     bool dragEnabled() const;
0143
0144     void setDragDropOverwriteMode(bool overwrite);
0145     bool dragDropOverwriteMode() const;
0146
0147     enum DragDropMode {
0148         NoDragDrop,
0149         DragOnly,
0150         DropOnly,
0151         DragDrop,
0152         InternalMove
0153     };
0154     Q_ENUM(DragDropMode)
0155
0156     void setDragDropMode(DragDropMode behavior);
0157     DragDropMode dragDropMode() const;
0158
0159     void setDefaultDropAction(Qt::DropAction dropAction);
0160     Qt::DropAction defaultDropAction() const;
0161 #endif
0162
0163     void setAlternatingRowColors(bool enable);
0164     bool alternatingRowColors() const;
0165
0166     void setIconSize(const QSize &size);
0167     QSize iconSize() const;
0168
0169     void setTextElideMode(Qt::TextElideMode mode);
0170     Qt::TextElideMode textElideMode() const;
0171
0172     virtual void keyboardSearch(const QString &search);
0173
0174     virtual QRect visualRect(const QModelIndex &index) const = 0;
0175     virtual void scrollTo(const QModelIndex &index, ScrollHint hint = EnsureVisible) = 0;
0176     virtual QModelIndex indexAt(const QPoint &point) const = 0;
0177
0178     QSize sizeHintForIndex(const QModelIndex &index) const;
0179     virtual int sizeHintForRow(int row) const;
0180     virtual int sizeHintForColumn(int column) const;
0181
0182     int updateThreshold() const;
0183     void setUpdateThreshold(int threshold);
0184
0185     void openPersistentEditor(const QModelIndex &index);
0186     void closePersistentEditor(const QModelIndex &index);
0187     bool isPersistentEditorOpen(const QModelIndex &index) const;
0188
0189     void setIndexWidget(const QModelIndex &index, QWidget *widget);
0190     QWidget *indexWidget(const QModelIndex &index) const;
0191
0192     void setItemDelegateForRow(int row, QAbstractItemDelegate *delegate);
0193     QAbstractItemDelegate *itemDelegateForRow(int row) const;
0194
0195     void setItemDelegateForColumn(int column, QAbstractItemDelegate *delegate);
0196     QAbstractItemDelegate *itemDelegateForColumn(int column) const;
0197
0198 #if QT_DEPRECATED_SINCE(6, 0)
0199     QT_DEPRECATED_VERSION_X_6_0("Use itemDelegateForIndex instead")
0200     QAbstractItemDelegate *itemDelegate(const QModelIndex &index) const
0201     { return itemDelegateForIndex(index); }
0202 #endif
0203     virtual QAbstractItemDelegate *itemDelegateForIndex(const QModelIndex &index) const;
0204
0205     virtual QVariant inputMethodQuery(Qt::InputMethodQuery query) const override;
0206
0207     using QWidget::update;
0208
0209 public Q_SLOTS:
0210     virtual void reset();
0211     virtual void setRootIndex(const QModelIndex &index);
0212     virtual void doItemsLayout();
0213     virtual void selectAll();
0214     void edit(const QModelIndex &index);
0215     void clearSelection();
0216     void setCurrentIndex(const QModelIndex &index);
0217     void scrollToTop();
0218     void scrollToBottom();
0219     void update(const QModelIndex &index);
0220
0221 protected Q_SLOTS:
0222     virtual void dataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight,
0223                              const QList<int> &roles = QList<int>());
0224     virtual void rowsInserted(const QModelIndex &parent, int start, int end);
0225     virtual void rowsAboutToBeRemoved(const QModelIndex &parent, int start, int end);
0226     virtual void selectionChanged(const QItemSelection &selected, const QItemSelection &deselected);
0227     virtual void currentChanged(const QModelIndex &current, const QModelIndex &previous);
0228     virtual void updateEditorData();
0229     virtual void updateEditorGeometries();
0230     virtual void updateGeometries();
0231     virtual void verticalScrollbarAction(int action);
0232     virtual void horizontalScrollbarAction(int action);
0233     virtual void verticalScrollbarValueChanged(int value);
0234     virtual void horizontalScrollbarValueChanged(int value);
0235     virtual void closeEditor(QWidget *editor, QAbstractItemDelegate::EndEditHint hint);
0236     virtual void commitData(QWidget *editor);
0237     virtual void editorDestroyed(QObject *editor);
0238
0239 Q_SIGNALS:
0240     void pressed(const QModelIndex &index);
0241     void clicked(const QModelIndex &index);
0242     void doubleClicked(const QModelIndex &index);
0243
0244     void activated(const QModelIndex &index);
0245     void entered(const QModelIndex &index);
0246     void viewportEntered();
0247
0248     void iconSizeChanged(const QSize &size);
0249
0250 protected:
0251     QAbstractItemView(QAbstractItemViewPrivate &, QWidget *parent = nullptr);
0252
0253     enum CursorAction { MoveUp, MoveDown, MoveLeft, MoveRight,
0254                         MoveHome, MoveEnd, MovePageUp, MovePageDown,
0255                         MoveNext, MovePrevious };
0256     virtual QModelIndex moveCursor(CursorAction cursorAction,
0257                                    Qt::KeyboardModifiers modifiers) = 0;
0258
0259     virtual int horizontalOffset() const = 0;
0260     virtual int verticalOffset() const = 0;
0261
0262     virtual bool isIndexHidden(const QModelIndex &index) const = 0;
0263
0264     virtual void setSelection(const QRect &rect, QItemSelectionModel::SelectionFlags command) = 0;
0265     virtual QRegion visualRegionForSelection(const QItemSelection &selection) const = 0;
0266     virtual QModelIndexList selectedIndexes() const;
0267
0268     virtual bool edit(const QModelIndex &index, EditTrigger trigger, QEvent *event);
0269
0270     virtual QItemSelectionModel::SelectionFlags selectionCommand(const QModelIndex &index,
0271                                                                  const QEvent *event = nullptr) const;
0272
0273 #if QT_CONFIG(draganddrop)
0274     virtual void startDrag(Qt::DropActions supportedActions);
0275 #endif
0276
0277     virtual void initViewItemOption(QStyleOptionViewItem *option) const;
0278
0279     enum State {
0280         NoState,
0281         DraggingState,
0282         DragSelectingState,
0283         EditingState,
0284         ExpandingState,
0285         CollapsingState,
0286         AnimatingState
0287     };
0288
0289     State state() const;
0290     void setState(State state);
0291
0292     void scheduleDelayedItemsLayout();
0293     void executeDelayedItemsLayout();
0294
0295     void setDirtyRegion(const QRegion &region);
0296     void scrollDirtyRegion(int dx, int dy);
0297     QPoint dirtyRegionOffset() const;
0298
0299     void startAutoScroll();
0300     void stopAutoScroll();
0301     void doAutoScroll();
0302
0303     bool focusNextPrevChild(bool next) override;
0304     bool event(QEvent *event) override;
0305     bool viewportEvent(QEvent *event) override;
0306     void mousePressEvent(QMouseEvent *event) override;
0307     void mouseMoveEvent(QMouseEvent *event) override;
0308     void mouseReleaseEvent(QMouseEvent *event) override;
0309     void mouseDoubleClickEvent(QMouseEvent *event) override;
0310 #if QT_CONFIG(draganddrop)
0311     void dragEnterEvent(QDragEnterEvent *event) override;
0312     void dragMoveEvent(QDragMoveEvent *event) override;
0313     void dragLeaveEvent(QDragLeaveEvent *event) override;
0314     void dropEvent(QDropEvent *event) override;
0315 #endif
0316     void focusInEvent(QFocusEvent *event) override;
0317     void focusOutEvent(QFocusEvent *event) override;
0318     void keyPressEvent(QKeyEvent *event) override;
0319     void resizeEvent(QResizeEvent *event) override;
0320     void timerEvent(QTimerEvent *event) override;
0321     void inputMethodEvent(QInputMethodEvent *event) override;
0322     bool eventFilter(QObject *object, QEvent *event) override;
0323
0324 #if QT_CONFIG(draganddrop)
0325     enum DropIndicatorPosition { OnItem, AboveItem, BelowItem, OnViewport };
0326     DropIndicatorPosition dropIndicatorPosition() const;
0327 #endif
0328
0329     QSize viewportSizeHint() const override;
0330
0331 private:
0332     Q_DECLARE_PRIVATE(QAbstractItemView)
0333     Q_DISABLE_COPY(QAbstractItemView)
0334
0335     friend class ::tst_QAbstractItemView;
0336     friend class ::tst_QTreeView;
0337     friend class QTreeViewPrivate; // needed to compile with MSVC
0338     friend class QListModeViewBase;
0339     friend class QListViewPrivate;
0340     friend class QAbstractSlider;
0341     friend class QComboBoxPrivate; // needed to call initViewItemOption
0342 };
0343
0344 Q_DECLARE_OPERATORS_FOR_FLAGS(QAbstractItemView::EditTriggers)
0345
0346 QT_END_NAMESPACE
0347
0348 #endif // QABSTRACTITEMVIEW_H