File indexing completed on 2024-05-19 07:42:18

0001 /*
0002  *    SPDX-FileCopyrightText: 2021 Waqar Ahmed <waqar.17a@gmail.com>
0003  *
0004  *    SPDX-License-Identifier: LGPL-2.0-or-later
0005  */
0006 #ifndef KCOMMANDBAR_H
0007 #define KCOMMANDBAR_H
0008 
0009 #include "kconfigwidgets_export.h"
0010 
0011 #include <QFrame>
0012 #include <memory>
0013 
0014 /**
0015  * @class KCommandBar kcommandbar.h KCommandBar
0016  *
0017  * @short A hud style menu which allows listing and executing actions
0018  *
0019  * KCommandBar takes as input a list of QActions and then shows them
0020  * in a "list-like-view" with a filter line edit. This allows quickly
0021  * executing an action.
0022  *
0023  * Usage is simple. Just create a KCommandBar instance when you need it
0024  * and throw it away once the user is done with it. You can store it as
0025  * a class member as well but there is little benefit in that. Example:
0026  *
0027  * @code
0028  * void slotOpenCommandBar()
0029  * {
0030  *      // `this` is important, you must pass a parent widget
0031  *      // here. Ideally it will be your mainWindow
0032  *     KCommandBar *bar = new KCommandBar(this);
0033  *
0034  *     // Load actions into the command bar
0035  *     // These actions can be from your menus / toolbars etc
0036  *     QList<ActionGroup> actionGroups = ...;
0037  *     bar->setActions(actionGroups);
0038  *
0039  *     // Show
0040  *     bar->show();
0041  * }
0042  * @endcode
0043  *
0044  * @since 5.83
0045  * @author Waqar Ahmed <waqar.17a@gmail.com>
0046  */
0047 class KCONFIGWIDGETS_EXPORT KCommandBar : public QFrame
0048 {
0049     Q_OBJECT
0050 
0051 public:
0052     /**
0053      * Represents a list of action that belong to the same group.
0054      * For example:
0055      * - All actions under the menu "File" or "Tool"
0056      */
0057     struct ActionGroup {
0058         QString name;
0059         QList<QAction *> actions;
0060     };
0061 
0062     /**
0063      * constructor
0064      *
0065      * @p parent is used to determine position and size of the
0066      * command bar. It *must* not be @c nullptr.
0067      */
0068     explicit KCommandBar(QWidget *parent);
0069     ~KCommandBar() override;
0070 
0071     /**
0072      * @p actions is a list of {GroupName, QAction}. Group name can be the name
0073      * of the component/menu where a QAction lives, for example in a menu "File -> Open File",
0074      * "File" should be the GroupName.
0075      */
0076     void setActions(const QList<ActionGroup> &actions);
0077 
0078 public Q_SLOTS:
0079     void show();
0080 
0081 protected:
0082     bool eventFilter(QObject *obj, QEvent *event) override;
0083 
0084 private:
0085     std::unique_ptr<class KCommandBarPrivate> const d;
0086 };
0087 
0088 Q_DECLARE_TYPEINFO(KCommandBar::ActionGroup, Q_RELOCATABLE_TYPE);
0089 
0090 #endif