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