src/lib/assistant.h

0001 /*
0002     SPDX-License-Identifier: GPL-2.0-or-later
0003     SPDX-FileCopyrightText: 2009 Alexander Rieder <alexanderrieder@gmail.com>
0004 */
0005
0006 #ifndef _ASSISTANT_H
0007 #define _ASSISTANT_H
0008
0009 #include <KXMLGUIClient>
0010 #include <QObject>
0011 #include <KPluginMetaData>
0012
0013 #include "cantor_export.h"
0014
0015 namespace Cantor
0016 {
0017 class Backend;
0018 class AssistantPrivate;
0019
0020 /**
0021  * An Assistant is a dialog for simplifying common tasks, like integrating, solving, or running scripts
0022  * To perform their task, they rely on one or more Extensions, to translate to the backends specific syntax.
0023  * @see Extension
0024  */
0025 class CANTOR_EXPORT Assistant : public QObject, public KXMLGUIClient
0026 {
0027   Q_OBJECT
0028   public:
0029     /**
0030      * Create a new assistant
0031      * @param parent the parent Object @see QObject
0032      **/
0033     explicit Assistant( QObject* parent );
0034     /**
0035      * Destructor
0036      */
0037     ~Assistant() override;
0038
0039     /**
0040      * Sets the backend, this Assistant operates on
0041      * @param backend the new backend
0042      */
0043     void setBackend(Backend* backend);
0044
0045     /**
0046      * Sets the properties of this Assistant
0047      * according to KPluginMetaData
0048      * @param info KPluginMetaData
0049      */
0050     void setPluginInfo(const KPluginMetaData &info);
0051
0052     /**
0053      * Returns a list of all extensions, the current backend
0054      * must provide to make this Assistant work. If it doesn't
0055      * this Assistant won't be shown in the Menu
0056      * @return list of required extensions
0057     */
0058     QStringList requiredExtensions();
0059
0060     /**
0061      * shows the assistants dialog or gui it offers, and returns a list of commands
0062      * to be run, to achieve the desired effect
0063      * @param parent the parent widget, each created Widget should use
0064      */
0065     virtual QStringList run(QWidget* parent) = 0;
0066
0067     /**
0068      * initialize the needed KActions/integrate into the menu bars
0069      */
0070     virtual void initActions() = 0;
0071
0072     /**
0073      * Returns the icon, this Assistant is using
0074      * @return icon, this Assistant is using
0075      */
0076     QString icon();
0077     /**
0078      * Returns the name of the assistant
0079      * @return name of the assistant
0080      */
0081     QString name();
0082     /**
0083      * Returns the backend, this assistant operates on
0084      * @return backend, this assistant operates on
0085      */
0086     Backend* backend();
0087
0088   Q_SIGNALS:
0089     /**
0090      * signal emitted, if the user has requested this Assistant to run
0091      * e.g. by clicking on its action in the menu
0092      */
0093     void requested();
0094
0095   private:
0096     AssistantPrivate* d;
0097 };
0098
0099 }
0100 #endif /* _ASSISTANT_H */