Warning, file /education/cantor/src/lib/graphicpackage.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: 2020 Sirgienko Nikita <warquark@gmail.com>
0004 */
0005 
0006 #ifndef _GRAPHICPACKAGE_H
0007 #define _GRAPHICPACKAGE_H
0008 
0009 #include <QList>
0010 #include <QString>
0011 
0012 #include "cantor_export.h"
0013 
0014 namespace Cantor
0015 {
0016 class GraphicPackagePrivate;
0017 class Session;
0018 class Expression;
0019 
0020 /**
0021  * This class represents of embedded graphic handler for certaion graphical package some of @c Backend
0022  * It provides access to native backend code (octave code for Octave backend, python code for Python backend, etc)
0023  * for few operations, which need for embedded graphics.
0024  *
0025  * @author Nikita Sirgienko
0026  */
0027 
0028 class CANTOR_EXPORT GraphicPackage {
0029 public:
0030     /// @c GraphicPackage can be only copied or load from disk via loadFromFile() function. Direct construction prohibited.
0031     GraphicPackage(const GraphicPackage&);
0032     ~GraphicPackage();
0033 
0034     /// This is id of graphical package. Must be unique, because the id used in search operations
0035     QString id() const;
0036 
0037     /// Name of package, which will be shown to user in some situation. Can be nonunique.
0038     QString name() const;
0039 
0040     /**
0041      * @brief This methor return @c Expression object, which will check requirements of the package.
0042      *
0043      * For example, using "matplotlib" graphic package for Python backend have sense only if Python module "matplotlib" installed.
0044      * So, the expression from @c isAvailable for "matplotlib" graphic package will check, if this module installed
0045      * @return Expression, which will have output @c "1" if requirements are fulfilled and "0" or just an error if they aren't fulfilled
0046      */
0047     Expression* isAvailable(Session*) const;
0048 
0049     /**
0050      * @brief This command should return code, which will enable capturing images.
0051      *
0052      * The command must be revertable, see disableSupportCommand().
0053      * @c additionalInfo This is additional parameter from backend, which go to @c "%1" template. This is optional.
0054      */
0055     QString enableSupportCommand(QString additionalInfo = QString()) const;
0056 
0057     /// This command should return code, which will disable capturing images.
0058     QString disableSupportCommand() const;
0059 
0060     /**
0061      * @brief The method return @c true if plot command empty and @c false otherwise
0062      *
0063      * The packages can have two realization of capturing.
0064      * 1. Need only enable/disable commands. Capturing is realising via plot function changing, etc.
0065      * 2. Need also additional run plot command after each entry with some arguments from @c Cantor::Expression object, see savePlotCommand()
0066      *
0067      * If the package is implemented in the first way, it must have empty plot command template (see savePlotCommand()), then isHavePlotCommand() will return @c true.
0068      * Otherwise, isHavePlotCommand() will return @c false.
0069      */
0070     bool isHavePlotCommand() const;
0071 
0072     /**
0073      * @brief This function return command for saving image result(s) from expression (if results are existed).
0074      * @param filenamePrefix Prefix of files with plots. Can be something like @c "/tmp/cantor_octave_2432_plot". Optional parameter.
0075      * @param plotNumber Currect plot number, should be used for full filename construction. Optional parameter.
0076      * @param additionalInfo This is additional parameter from backend, which go to @c "%3" template. Optional parameter.
0077      * @return Command which will save plot to certain file or empty string (see isHavePlotCommand())
0078      */
0079     QString savePlotCommand(QString filenamePrefix = QString(), int plotNumber = -1, QString additionalInfo = QString()) const;
0080 
0081     /**
0082      * Some graphic package can't capture plots correctly, for example, some packages can't test precense of created plot.
0083      * So, the package handling need some code for testing of plot command precense
0084      * This method return list of some strings, which should be in plot command.
0085      * @return List of strings, which should be in plot command or empty list.
0086      */
0087     const QStringList& plotCommandPrecentsKeywords() const;
0088 
0089     /**
0090      * @brief Load graphic packages from XML file.
0091      *
0092      * The file should have @c "GraphicPackages" root element with one or more @c "GraphicPackage" XML elements.
0093      * @code{.xml}
0094      * <GraphicPackages>
0095      *   <GraphicPackage>
0096      *     ..
0097      *   </GraphicPackage>
0098      *   ...
0099      * </GraphicPackages>
0100      * @endcode
0101      *
0102      * Scheme of the @c GraphicPackage element:
0103      * @code{.xml}
0104      * <GraphicPackage>
0105      *   <Id>...</Id>
0106      *   <Name>...</Name>
0107      *   <TestPresenceCommand>...</TestPresenceCommand>
0108      *   <EnableCommand>...</EnableCommand>
0109      *   <DisableCommand>...</DisableCommand>
0110      *   <ToFileCommandTemplate>...</ToFileCommandTemplate>
0111      * </GraphicPackage>
0112      * @endcode
0113      */
0114     static QList<GraphicPackage> loadFromFile(const QString& filename);
0115 
0116     /**
0117      * Some helper for searching @c package inside @c list of packages.
0118      */
0119     static int findById(const GraphicPackage& package, const QList<GraphicPackage>& list);
0120 
0121 private:
0122     GraphicPackage();
0123 
0124     GraphicPackagePrivate* d;
0125 };
0126 
0127 }
0128 #endif /* _GRAPHICPACKAGE_H */