File indexing completed on 2024-06-16 10:10:30

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2008 Michael Jansen <kde@michael-jansen.biz>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KACTIONCATEGORY_H
0009 #define KACTIONCATEGORY_H
0010 
0011 #include <kxmlgui_export.h>
0012 
0013 #include <QList>
0014 #include <QObject>
0015 #include <QString>
0016 #include <memory>
0017 
0018 #include <KStandardAction>
0019 
0020 #include "kactioncollection.h"
0021 
0022 struct KActionCategoryPrivate;
0023 
0024 class QAction;
0025 
0026 /**
0027  * @class KActionCategory kactioncategory.h KActionCategory
0028  *
0029  * Categorize actions for KShortcutsEditor.
0030  *
0031  * KActionCategory provides a second level to organize the actions in
0032  * KShortcutsEditor.
0033  *
0034  * The first possibility is using more than one action collection. Each
0035  * actions collection becomes a top level node.
0036  *
0037  * + action collection 1
0038  *   + first action
0039  *   + second action
0040  *   + third action
0041  * + action collection 2
0042  *   + first action
0043  *   + second action
0044  *   + third action
0045  *
0046  * Using KActionCategory it's possible to group the actions of one collection.
0047  * + action collection 1
0048  *   + first action
0049  *   + first category
0050  *     + action 1 in category
0051  *     + action 2 in category
0052  *   + second action
0053  *
0054  * \section Usage
0055  *
0056  * The usage is analog to action collections. Just create a category and use
0057  * it instead of the collection to create the actions.
0058  *
0059  * The synchronization between KActionCollection and KActionCategory is done
0060  * internally. There is for example no need to remove actions from a category.
0061  * It is done implicitly if the action is removed from the associated
0062  * collection.
0063  *
0064  * \code
0065  *
0066  * KActionCategory *file = new KActionCategory(i18n("File"), actionCollection());
0067  * file->addAction(
0068  *      KStandardAction::New,   //< see KStandardAction
0069  *      this,                   //< Receiver
0070  *      SLOT(fileNew()));       //< SLOT
0071  *
0072  * ... more actions added to file ...
0073  *
0074  * KActionCategory *edit = new KActionCategory(i18n("Edit"), actionCollection());
0075  * edit->addAction(
0076  *      KStandardAction::Copy,  //< see KStandardAction
0077  *      this,                   //< Receiver
0078  *      SLOT(fileNew()));       //< SLOT
0079  *
0080  * ...
0081  *
0082  * \endcode
0083  */
0084 class KXMLGUI_EXPORT KActionCategory : public QObject
0085 {
0086     Q_OBJECT
0087 
0088     Q_PROPERTY(QString text READ text WRITE setText)
0089 
0090 public:
0091     /**
0092      * Default constructor
0093      */
0094     explicit KActionCategory(const QString &text, KActionCollection *parent = nullptr);
0095 
0096     /**
0097      * Destructor
0098      */
0099     ~KActionCategory() override;
0100 
0101     /**
0102      * \name Adding Actions
0103      *
0104      * Add a action to the category.
0105      *
0106      * This methods are provided for your convenience. They call the
0107      * corresponding method of KActionCollection.
0108      */
0109     //@{
0110     QAction *addAction(const QString &name, QAction *action);
0111 
0112     QAction *addAction(KStandardAction::StandardAction actionType, const QObject *receiver = nullptr, const char *member = nullptr);
0113 
0114     QAction *addAction(KStandardAction::StandardAction actionType, const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
0115 
0116     QAction *addAction(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr);
0117 
0118     template<class ActionType>
0119     ActionType *add(const QString &name, const QObject *receiver = nullptr, const char *member = nullptr)
0120     {
0121         ActionType *action = collection()->add<ActionType>(name, receiver, member);
0122         addAction(action);
0123         return action;
0124     }
0125 
0126     //@}
0127 
0128     /**
0129      * Returns the actions belonging to this category
0130      */
0131     const QList<QAction *> actions() const;
0132 
0133     /**
0134      * The action collection this category is associated with.
0135      */
0136     KActionCollection *collection() const;
0137 
0138     /**
0139      * The action categorys descriptive text
0140      */
0141     QString text() const;
0142 
0143     /**
0144      * Set the action categorys descriptive text.
0145      */
0146     void setText(const QString &text);
0147 
0148 private:
0149     /**
0150      * Remove \action from this category if found.
0151      */
0152     KXMLGUI_NO_EXPORT void unlistAction(QAction *action);
0153 
0154     /**
0155      * Add action to category
0156      */
0157     void addAction(QAction *action); // exported because called from template method ActionType *add<ActionType>(...)
0158 
0159 private:
0160     //! KActionCollection needs access to some of our helper methods
0161     friend class KActionCollectionPrivate;
0162 
0163     //! Implementation details
0164     std::unique_ptr<KActionCategoryPrivate> const d;
0165 };
0166 
0167 #endif /* #ifndef KACTIONCATEGORY_H */