Warning, file /education/cantor/src/lib/backend.h was not indexed or was modified since last indexation (in which case cross-reference links may be missing, inaccurate or erroneous).

0001 /*
0002     SPDX-License-Identifier: GPL-2.0-or-later
0003     SPDX-FileCopyrightText: 2009 Alexander Rieder <alexanderrieder@gmail.com>
0004 */
0005 
0006 #ifndef _BACKEND_H
0007 #define _BACKEND_H
0008 
0009 #include <QObject>
0010 #include <QVariant>
0011 #include <KXMLGUIClient>
0012 #include <KPluginInfo>
0013 
0014 #include "graphicpackage.h"
0015 
0016 #include "cantor_export.h"
0017 
0018 class KConfigSkeleton;
0019 class QWidget;
0020 
0021 /**
0022  * Namespace collecting all Classes of the Cantor Libraries
0023  */
0024 namespace Cantor
0025 {
0026 class Session;
0027 class Extension;
0028 class BackendPrivate;
0029 
0030 /**
0031  * The Backend class provides access to information about the backend.
0032  * It provides access to what features are supported by the backend, and
0033  * a factory method to create a new Session
0034  * It needs to be subclassed by all Backends.
0035  *
0036  * @author Alexander Rieder
0037  */
0038 
0039 class CANTOR_EXPORT Backend : public QObject, public KXMLGUIClient
0040 {
0041   Q_OBJECT
0042   public:
0043     /**
0044      * This enum is used to specify the Features, supported by a backend.
0045      */
0046     enum Capability{
0047         Nothing = 0x0,             ///< the Backend doesn't support any of the optional features
0048         LaTexOutput = 0x1,         ///< it can output results as LaTeX code
0049         InteractiveMode = 0x2,     /**< it supports an interactive workflow. (It means a command
0050                                         can ask for additional input while running)
0051                                    */
0052         SyntaxHighlighting = 0x4,  ///< it offers a custom Syntax Highlighter
0053         Completion = 0x8,          ///< it offers completion of partially typed commands
0054         SyntaxHelp = 0x10,         /**< it offers help about a commands syntax, that will
0055                                         be shown in a tooltip
0056                                    */
0057         VariableManagement = 0x20, ///< it offers access to the variables (for variable management panel)
0058         IntegratedPlots = 0x40,    ///< it offers, that backend supports plot not only as separate window, but also image result
0059     };
0060     Q_DECLARE_FLAGS(Capabilities, Capability)
0061 
0062   protected:
0063     /**
0064      * Create a new Backend. Normally the static createBackend factory method
0065      * should be used.
0066      * @param parent the Parent object
0067      * @param args optional arguments (not used)
0068      */
0069     explicit Backend( QObject* parent = nullptr,const QList<QVariant>& args=QList<QVariant>() );
0070     /**
0071      * Destructor. Doesn't anything.
0072      */
0073     ~Backend() override;
0074 
0075   public:
0076 
0077     /**
0078      * Creates a new Session. It is the way to go to create a Session,
0079      * don't call new Session on your own.
0080      * @return a new Session of this Backend, or 0 if creating failed
0081      */
0082     virtual Session* createSession() = 0;
0083     /**
0084      * Returns list of the supported optional features
0085      * @return a list of features, containing items of the Capability enum, ORed together
0086      */
0087     virtual Capabilities capabilities() const = 0;
0088     /**
0089      * Returns whether all of this backends requirements are fulfilled, or if some are missing.
0090      * @param reason if set, backend write information about missing requirements, if they exists
0091      * @return @c true if all the requirements needed to use this Backend are fulfilled
0092      * @return @c false some requirements are missing. e.g. the maxima executable can not be found
0093      * @see Capability
0094     */
0095     virtual bool requirementsFullfilled(QString* const reason = nullptr) const = 0;
0096 
0097     /**
0098      * Returns a unique string to identify this backend.
0099      * In contrast to name() this string isn't translated
0100      * @return string to identify backend
0101      */
0102     virtual QString id() const = 0;
0103 
0104     /**
0105      * Returns the recommended version of the backend supported by Cantor
0106      * @return the recommended version of the backend
0107      */
0108     virtual QString version() const = 0;
0109 
0110     //Stuff extracted from the .desktop file
0111     /**
0112      * Returns the name of the backend
0113      * @return the backends name
0114      */
0115     QString name() const;
0116 
0117     /**
0118      * Returns a short comment about the backend.
0119      * @return comment about the backend
0120      */
0121     QString comment() const;
0122     /**
0123      * Returns the icon to use with this backend
0124      * @return name of the icon
0125      */
0126     QString icon() const;
0127     /**
0128      * Returns the Url of the Homepage for the Backend
0129      * @return the url
0130      */
0131     QString url() const;
0132     /**
0133      * Returns an Url pointing to the Help of the Backend
0134      * The method should be overwritten by all Backends(who have an online help)
0135      * You should make the returned Url translatable, e.g. by doing something like:
0136      * return i18nc("the url to the documentation of KAlgebra, please check if there is a translated version and use the correct url",
0137      *   "https://docs.kde.org/?application=kalgebra");
0138      * @return Url of the help
0139      */
0140     virtual QUrl helpUrl() const = 0;
0141 
0142     /**
0143      * Returns the text that should be shown on default in the HelpPanel when it's initially created.
0144      * This text can contain the information for who to use the integrated help available in some backends like Maxima and R.
0145      */
0146     virtual QString defaultHelp() const;
0147 
0148     /**
0149      * Returns if the backend should be enabled (shown in the Backend dialog)
0150      * @return @c true, if the enabled flag is set to true, and the requirements are fulfilled
0151      * @return @c false, if the backend was purposely disabled, or requirements are missing
0152      * @see requirementsFullfilled()
0153      */
0154     bool isEnabled() const;
0155     /**
0156      * Enables/disables this backend
0157      * @param enabled true to enable backend false to disable
0158      */
0159     void setEnabled(bool enabled);
0160 
0161     /**
0162      * Returns a longer description of the Backend, e.g. purpose, strengths etc.
0163      * It should help the user to decide between the different Backends
0164      * @return a description of the backend. It can contain html
0165      */
0166     virtual QString description() const;
0167     /**
0168      * Returns a Widget for configuring this backend
0169      * @return Widget for usage in the Settings dialog
0170      */
0171     virtual QWidget* settingsWidget(QWidget* parent) const = 0;
0172     /**
0173      * Returns a KConfig object, containing all the settings,
0174      * the backend might need
0175      * @return a KConfigSkeleton object, for configuring this backend
0176      */
0177     virtual KConfigSkeleton* config() const = 0;
0178     /**
0179      * Returns a list of the names of all the Extensions supported by this backend
0180      * @return a list of the names of all the Extensions supported by this backend
0181      * @see extension(const QString& name)
0182      */
0183     QStringList extensions() const;
0184     /**
0185      * Returns an Extension of this backend for the given name, or null
0186      * if the Backend doesn't have an extension with this name.
0187      * @return Pointer to the Extension object with the given name
0188      */
0189     Extension* extension(const QString& name) const;
0190 
0191     /**
0192      * Returns a list of the names of all the installed and enabled backends
0193      * @return a list of the names of all the installed and enabled backends
0194      * @see isEnabled()
0195      */
0196     static QStringList listAvailableBackends();
0197     /**
0198      * Returns Pointers to all the installed backends
0199      * @return Pointers to all the installed backends
0200      */
0201     static QList<Backend*> availableBackends();
0202     /**
0203      * Returns the backend with the given name, or null if it isn't found
0204      * @return the backend with the given name, or null if it isn't found
0205      */
0206     static Backend* getBackend(const QString& name);
0207 
0208     /**
0209      * @return @c true if all the requirements (the path is correct, the file is executable, etc.) are fulfilled
0210      * for the backend @c Name with the path to the executable @c path and false otherwise.
0211      * In case the requrements are not fulfilled, the reason is written to @c reason.
0212      */
0213     static bool checkExecutable(const QString& name, const QString& path, QString* reason = nullptr);
0214 
0215     /**
0216      * This is test function, which allow test, that run @p program with @p args produce output file @p filename
0217      * with content @p expectedContent during time less that @p timeOut.
0218      * If something go wrong, problem will be described in @p reason, if the parameter is not @p nullptr.
0219      */
0220     static bool testProgramWritable(
0221         const QString& program, const QStringList& args, const QString& filename, const QString& expectedContent, QString* reason = nullptr, int timeOut = 5000
0222     );
0223 
0224     /**
0225      * This function will return list of all available workable graphics packages for integrated graphics
0226      */
0227     QList<GraphicPackage> availableGraphicPackages() const;
0228 
0229   private:
0230     BackendPrivate* d;
0231 };
0232 
0233 Q_DECLARE_OPERATORS_FOR_FLAGS(Backend::Capabilities)
0234 
0235 }
0236 
0237 #endif /* _BACKEND_H */