File indexing completed on 2024-05-05 04:05:48
0001 /* 0002 SPDX-FileCopyrightText: 2009, 2010 Stefan Majewsky <majewsky@gmx.net> 0003 0004 SPDX-License-Identifier: LGPL-2.0-or-later 0005 */ 0006 0007 #ifndef LIBPALA_SLICER_H 0008 #define LIBPALA_SLICER_H 0009 0010 #include "libpala_export.h" 0011 0012 #include <QObject> 0013 #include <QVariant> 0014 0015 #include <memory> 0016 0017 namespace Pala 0018 { 0019 class SlicerJob; 0020 class SlicerMode; 0021 class SlicerProperty; 0022 class SlicerPropertySet; 0023 0024 /** 0025 * \class Slicer slicer.h <Pala/Slicer> 0026 * \brief Representation of a slicing algorithm. 0027 * 0028 * This class represents a slicing algorithm. It has to be subclassed by slicing plugin developers. Subclasses need to implement 0029 * \li the constructor (where the slicer's properties and, if used, the modes have to be instantiated) 0030 * \li the run() method (where the actual slicing is performed). 0031 * 0032 * Additionally, the class must be flagged as entry point into the plugin, with the following code: 0033 \code 0034 class MySlicer : public Pala::Slicer { ... }; 0035 0036 #include <KPluginFactory> 0037 0038 K_PLUGIN_FACTORY(MySlicerFactory, registerPlugin<MySlicer>();) 0039 K_EXPORT_PLUGIN(MySlicerFactory("myslicer")) 0040 \endcode 0041 * In the last line, put inside the string literal the file name of the plugin library (e.g. \a myslicer is the name for a library \a libmyslicer.so on unixoid systems, or \a myslicer.dll on Windows systems). 0042 */ 0043 class LIBPALA_EXPORT Slicer : public QObject 0044 { 0045 Q_OBJECT 0046 public: 0047 /** 0048 * \brief Behavioral flags of a slicer. 0049 * These flags can be used to programmatically configure the behavior of libpala for a single slicer. You should only set the slicer's flags once in the constructor, and not modify it later. (The latter might cause unexpected behavior.) 0050 * \see setFlags 0051 */ 0052 enum SlicerFlag 0053 { 0054 NoFlags = 0x0, 0055 AllowFullTransparency = 0x1 ///< By default, libpala will increase the minimum alpha value of input images to avoid invisible pieces. Set this flag if you rely on the alpha channel in your slicing algorithm. 0056 }; 0057 Q_DECLARE_FLAGS(SlicerFlags, SlicerFlag) 0058 0059 /** 0060 * \brief Constructs a new Slicer object. 0061 * In any subclass, the constructor signature has to be the same (due to the way the plugin loader works). The arguments should be passed to this constructor and ignored by the subclass implementation, as their format might change without notice in future versions. 0062 */ 0063 explicit Slicer(QObject* parent = nullptr, const QVariantList& args = QVariantList()); 0064 ///Deletes this slicer, and all properties and modes which have been added with addProperty() and addMode(). 0065 ~Slicer() override; 0066 0067 //The following function belongs to the interface to the Palapeli application. It is not documented because the documentation is targeted at slicer developers. 0068 ///\internal 0069 ///\since libpala 1.2 (KDE SC 4.6) 0070 QList<const Pala::SlicerMode*> modes() const; 0071 ///\internal 0072 ///\deprecated because sorting order is not right 0073 QMap<QByteArray, const Pala::SlicerProperty*> properties() const; 0074 ///\internal 0075 ///\since libpala 1.2 (KDE SC 4.6) 0076 QList<const Pala::SlicerProperty*> propertyList() const; //BIC: rename to properties() 0077 ///\internal 0078 SlicerFlags flags() const; 0079 ///\internal 0080 bool process(Pala::SlicerJob* job); //a wrapper function for Pala::Slicer::run 0081 //BIC: constify method 0082 0083 //This class is the only interface that slicers can use to communicate with Palapeli, and it is only instantiated very few times (one instance per slicer plugin), so it should be reasonable to reserve some space in the virtual table for future additions. 0084 //RESERVE_VIRTUAL_5 0085 protected: 0086 ///Add the given property to the property list of this slicer. The slicer will take care of destructing the given Pala::SlicerProperty instance when it is destructed. 0087 ///Use this method in the subclass constructors to fill the slicer with properties. Properties let the user control how the slicing is done. 0088 ///\warning It is not safe to add new properties outside the constructor of a Pala::Slicer subclass. 0089 void addProperty(const QByteArray& key, Pala::SlicerProperty* property); 0090 //BIC: make interface similar to setMode() 0091 ///Add an operation mode to this slicer. The slicer will take care of destructing the given Pala::SlicerMode instance when it is destructed. 0092 ///You may use modes e.g. if your slicer includes different slicing algorithms at once which might need a different set of properties (see Pala::SlicerMode documentation for details). If you choose not to use modes, just ignore this function and all other functions concerning modes. 0093 ///\warning It is not safe to add new modes outside the constructor of a Pala::Slicer subclass. 0094 ///\since libpala 1.2 (KDE SC 4.6) 0095 void addMode(Pala::SlicerMode* mode); 0096 0097 friend class SlicerPropertySet; 0098 ///\see Pala::Slicer::SlicerFlags 0099 void setFlags(SlicerFlags flags); 0100 0101 /** 0102 * \brief The slicing algorithm. 0103 * Implement the slicing algorithm in this method. The slicing algorithm should always respect the current values of the slicer's properties, as defined through the addProperty() method. 0104 * \returns whether the operation has been completed successfully 0105 * \see Pala::SlicerJob 0106 */ 0107 virtual bool run(Pala::SlicerJob* job) = 0; 0108 //BIC: constify method 0109 private: 0110 std::unique_ptr<class SlicerPrivate> const d_ptr; 0111 Q_DECLARE_PRIVATE(Slicer) 0112 Q_DISABLE_COPY(Slicer) 0113 }; 0114 0115 Q_DECLARE_OPERATORS_FOR_FLAGS(Slicer::SlicerFlags) 0116 } 0117 0118 #endif // LIBPALA_SLICER_H