File indexing completed on 2024-02-18 03:58:07

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2007, 2009 Rafael Fernández López <ereslibre@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KCATEGORYDRAWER_H
0009 #define KCATEGORYDRAWER_H
0010 
0011 #include <kitemviews_export.h>
0012 
0013 #include <QMouseEvent>
0014 #include <QObject>
0015 #include <memory>
0016 
0017 class KCategoryDrawerPrivate;
0018 
0019 class QPainter;
0020 class QModelIndex;
0021 class QStyleOption;
0022 
0023 class KCategorizedView;
0024 
0025 /**
0026  * @class KCategoryDrawer kcategorydrawer.h KCategoryDrawer
0027  *
0028  * The category drawing is performed by this class. It also gives information about the category
0029  * height and margins.
0030  *
0031  */
0032 class KITEMVIEWS_EXPORT KCategoryDrawer : public QObject
0033 {
0034     Q_OBJECT
0035     friend class KCategorizedView;
0036 
0037 public:
0038     /*
0039      * Construct a category drawer for a given view
0040      *
0041      * @since 5.0
0042      */
0043     KCategoryDrawer(KCategorizedView *view);
0044     ~KCategoryDrawer() override;
0045 
0046     /**
0047      * @return The view this category drawer is associated with.
0048      */
0049     KCategorizedView *view() const;
0050 
0051     /**
0052      * This method purpose is to draw a category represented by the given
0053      * @param index with the given @param sortRole sorting role
0054      *
0055      * @note This method will be called one time per category, always with the
0056      *       first element in that category
0057      */
0058     virtual void drawCategory(const QModelIndex &index, int sortRole, const QStyleOption &option, QPainter *painter) const;
0059 
0060     /**
0061      * @return The category height for the category represented by index @p index with
0062      *         style options @p option.
0063      */
0064     virtual int categoryHeight(const QModelIndex &index, const QStyleOption &option) const;
0065 
0066     /**
0067      * @note 0 by default
0068      *
0069      * @since 4.4
0070      */
0071     virtual int leftMargin() const;
0072 
0073     /**
0074      * @note 0 by default
0075      *
0076      * @since 4.4
0077      */
0078     virtual int rightMargin() const;
0079 
0080 Q_SIGNALS:
0081     /**
0082      * This signal becomes emitted when collapse or expand has been clicked.
0083      */
0084     void collapseOrExpandClicked(const QModelIndex &index);
0085 
0086     /**
0087      * Emit this signal on your subclass implementation to notify that something happened. Usually
0088      * this will be triggered when you have received an event, and its position matched some "hot spot".
0089      *
0090      * You give this action the integer you want, and having connected this signal to your code,
0091      * the connected slot can perform the needed changes (view, model, selection model, delegate...)
0092      */
0093     void actionRequested(int action, const QModelIndex &index);
0094 
0095 protected:
0096     /**
0097      * Method called when the mouse button has been pressed.
0098      *
0099      * @param index The representative index of the block of items.
0100      * @param blockRect The rect occupied by the block of items.
0101      * @param event The mouse event.
0102      *
0103      * @warning You explicitly have to determine whether the event has been accepted or not. You
0104      *          have to call event->accept() or event->ignore() at all possible case branches in
0105      *          your code.
0106      */
0107     virtual void mouseButtonPressed(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
0108 
0109     /**
0110      * Method called when the mouse button has been released.
0111      *
0112      * @param index The representative index of the block of items.
0113      * @param blockRect The rect occupied by the block of items.
0114      * @param event The mouse event.
0115      *
0116      * @warning You explicitly have to determine whether the event has been accepted or not. You
0117      *          have to call event->accept() or event->ignore() at all possible case branches in
0118      *          your code.
0119      */
0120     virtual void mouseButtonReleased(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
0121 
0122     /**
0123      * Method called when the mouse has been moved.
0124      *
0125      * @param index The representative index of the block of items.
0126      * @param blockRect The rect occupied by the block of items.
0127      * @param event The mouse event.
0128      */
0129     virtual void mouseMoved(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
0130 
0131     /**
0132      * Method called when the mouse button has been double clicked.
0133      *
0134      * @param index The representative index of the block of items.
0135      * @param blockRect The rect occupied by the block of items.
0136      * @param event The mouse event.
0137      *
0138      * @warning You explicitly have to determine whether the event has been accepted or not. You
0139      *          have to call event->accept() or event->ignore() at all possible case branches in
0140      *          your code.
0141      */
0142     virtual void mouseButtonDoubleClicked(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
0143 
0144     /**
0145      * Method called when the mouse button has left this block.
0146      *
0147      * @param index The representative index of the block of items.
0148      * @param blockRect The rect occupied by the block of items.
0149      */
0150     virtual void mouseLeft(const QModelIndex &index, const QRect &blockRect);
0151 
0152 private:
0153     std::unique_ptr<KCategoryDrawerPrivate> const d;
0154 };
0155 
0156 #endif // KCATEGORYDRAWER_H