File indexing completed on 2024-04-14 14:25:50

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2007-2008 Rafael Fernández López <ereslibre@kde.org>
0004     SPDX-FileCopyrightText: 2008 Kevin Ottens <ervin@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KWIDGETITEMDELEGATE_H
0010 #define KWIDGETITEMDELEGATE_H
0011 
0012 #include <QAbstractItemDelegate>
0013 #include <QEvent>
0014 #include <QList>
0015 #include <QPersistentModelIndex>
0016 #include <memory>
0017 
0018 #include <kitemviews_export.h>
0019 
0020 class QObject;
0021 class QPainter;
0022 class QStyleOption;
0023 class QStyleOptionViewItem;
0024 class QAbstractItemView;
0025 class QItemSelection;
0026 
0027 class KWidgetItemDelegatePrivate;
0028 class KWidgetItemDelegatePool;
0029 
0030 /**
0031  * @class KWidgetItemDelegate kwidgetitemdelegate.h KWidgetItemDelegate
0032  *
0033  * This class allows to create item delegates embedding simple widgets to interact
0034  * with items. For instance you can add push buttons, line edits, etc. to your delegate
0035  * and use them to modify the state of your model.
0036  *
0037  * @since 4.1
0038  */
0039 class KITEMVIEWS_EXPORT KWidgetItemDelegate : public QAbstractItemDelegate
0040 {
0041     Q_OBJECT
0042 
0043 public:
0044     /**
0045      * Creates a new ItemDelegate to be used with a given itemview.
0046      *
0047      * @param itemView the item view the new delegate will monitor
0048      * @param parent the parent of this delegate
0049      */
0050     explicit KWidgetItemDelegate(QAbstractItemView *itemView, QObject *parent = nullptr);
0051 
0052     /**
0053      * Destroys an ItemDelegate.
0054      */
0055     ~KWidgetItemDelegate() override;
0056 
0057     /**
0058      * Retrieves the item view this delegate is monitoring.
0059      *
0060      * @return the item view this delegate is monitoring
0061      */
0062     QAbstractItemView *itemView() const;
0063 
0064     /**
0065      * Retrieves the currently focused index. An invalid index if none is focused.
0066      *
0067      * @return the current focused index, or QPersistentModelIndex() if none is focused.
0068      */
0069     QPersistentModelIndex focusedIndex() const;
0070 
0071     /**
0072      * trigger a modelReset
0073      */
0074     void resetModel();
0075 
0076 protected:
0077     /**
0078      * Creates the list of widgets needed for an item.
0079      *
0080      * @note No initialization of the widgets is supposed to happen here.
0081      *       The widgets will be initialized based on needs for a given item.
0082      *
0083      * @note If you want to connect some widget signals to any slot, you should
0084      *       do it here.
0085      *
0086      * @param index the index to create widgets for
0087      *
0088      * @return the list of newly created widgets which will be used to interact with an item.
0089      * @see updateItemWidgets()
0090      */
0091     virtual QList<QWidget *> createItemWidgets(const QModelIndex &index) const = 0;
0092 
0093     /**
0094      * Updates a list of widgets for its use inside of the delegate (painting or
0095      * event handling).
0096      *
0097      * @note All the positioning and sizing should be done in item coordinates.
0098      *
0099      * @warning Do not make widget connections in here, since this method will
0100      * be called very regularly.
0101      *
0102      * @param widgets the widgets to update
0103      * @param option the current set of style options for the view.
0104      * @param index the model index of the item currently manipulated.
0105      */
0106     virtual void updateItemWidgets(const QList<QWidget *> widgets, const QStyleOptionViewItem &option, const QPersistentModelIndex &index) const = 0;
0107     // KF6 TODO: add missing reference to widgets parameter
0108 
0109 #if KITEMVIEWS_ENABLE_DEPRECATED_SINCE(4, 2)
0110     /**
0111      * Paint the widgets of the item. This method is meant to be used in the paint()
0112      * method of your item delegate implementation.
0113      *
0114      * @param painter the painter the widgets will be painted on.
0115      * @param option the current set of style options for the view.
0116      * @param index the model index of the item currently painted.
0117      *
0118      * @deprecated Since 4.2 this method is not longer needed to be called. All widgets will kept
0119      *          updated without the need of calling paintWidgets() in your paint() event. For the
0120      *          widgets of a certain index to be updated your model has to emit dataChanged() on the
0121      *          indexes that want to be updated.
0122      */
0123     KITEMVIEWS_DEPRECATED_VERSION(4, 2, "Emit QAbstractItemModel::dataChanged(...) signal instead")
0124     void paintWidgets(QPainter *painter, const QStyleOptionViewItem &option, const QPersistentModelIndex &index) const;
0125 #endif
0126 
0127     /**
0128      * Sets the list of event @p types that a @p widget will block.
0129      *
0130      * Blocked events are not passed to the view. This way you can prevent an item
0131      * from being selected when a button is clicked for instance.
0132      *
0133      * @param widget the widget which must block events
0134      * @param types the list of event types the widget must block
0135      */
0136     void setBlockedEventTypes(QWidget *widget, QList<QEvent::Type> types) const;
0137     // KF6 TODO: pass types by const reference
0138 
0139     /**
0140      * Retrieves the list of blocked event types for the given widget.
0141      *
0142      * @param widget the specified widget.
0143      *
0144      * @return the list of blocked event types, can be empty if no events are blocked.
0145      */
0146     QList<QEvent::Type> blockedEventTypes(QWidget *widget) const;
0147 
0148 private:
0149     //@cond PRIVATE
0150     friend class KWidgetItemDelegatePool;
0151     friend class KWidgetItemDelegateEventListener;
0152     std::unique_ptr<class KWidgetItemDelegatePrivate> const d;
0153 
0154     Q_PRIVATE_SLOT(d, void _k_slotRowsInserted(const QModelIndex &, int, int))
0155     Q_PRIVATE_SLOT(d, void _k_slotRowsAboutToBeRemoved(const QModelIndex &, int, int))
0156     Q_PRIVATE_SLOT(d, void _k_slotRowsRemoved(const QModelIndex &, int, int))
0157     Q_PRIVATE_SLOT(d, void _k_slotDataChanged(const QModelIndex &, const QModelIndex &))
0158     Q_PRIVATE_SLOT(d, void _k_slotLayoutChanged())
0159     Q_PRIVATE_SLOT(d, void _k_slotModelReset())
0160     Q_PRIVATE_SLOT(d, void _k_slotSelectionChanged(const QItemSelection &, const QItemSelection &))
0161     //@endcond
0162 };
0163 
0164 #endif