Plugin.h

Go to the documentation of this file.

/*
 * Plugin.h - class plugin, the base-class and generic interface for all plugins
 *
 * Copyright (c) 2005-2014 Tobias Doerffel <tobydox/at/users.sourceforge.net>
 *
 * This file is part of LMMS - https://lmms.io
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 *
 * You should have received a copy of the GNU General Public
 * License along with this program (see COPYING); if not, write to the
 * Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301 USA.
 *
 */
 
#ifndef LMMS_PLUGIN_H
#define LMMS_PLUGIN_H
 
#include <QStringList>
#include <QMap>
 
#include "JournallingObject.h"
#include "Model.h"
 
 
class QWidget;
 
namespace lmms
{
 
class AutomatableModel;
class PixmapLoader;
 
namespace gui
{
 
class PluginView;
 
}

class LMMS_EXPORT Plugin : public Model, public JournallingObject
{
        Q_OBJECT
public:
        enum class Type
        {
                Instrument,     // instrument being used in channel-track
                Effect,         // effect-plugin for effect-board
                ImportFilter,   // filter for importing a file
                ExportFilter,   // filter for exporting a file
                Tool,           // additional tool (level-meter etc)
                Library,        // simple library holding a code-base for
                                // several other plugins (e.g. VST-support)
                Other,
                Undefined = 255
        } ;

        struct Descriptor
        {
                const char * name;
                const char * displayName;
                const char * description;
                const char * author;
                int version;
                Type type;
                const PixmapLoader * logo;
                const char * supportedFileTypes; 
 
                inline bool supportsFileType( const QString& extension ) const
                {
                        return QString( supportedFileTypes ).split( QChar( ',' ) ).contains( extension );
                }

                class LMMS_EXPORT SubPluginFeatures
                {
                public:
                        struct Key
                        {
                                using AttributeMap = QMap<QString, QString>;
 
                                inline Key( const Plugin::Descriptor * desc = nullptr,
                                                const QString & name = QString(),
                                                const AttributeMap & am = AttributeMap()
                                        )
                                        :
                                        desc( desc ),
                                        name( name ),
                                        attributes( am )
                                {
                                }
 
                                Key( const QDomElement & key );
 
                                QDomElement saveXML( QDomDocument & doc ) const;
 
                                inline bool isValid() const
                                {
                                        return desc != nullptr;
                                }

                                const Plugin::Descriptor* desc;
                                QString name;
                                AttributeMap attributes;
 
                                // helper functions to retrieve data that is
                                // not part of the key, but mapped via desc->subPluginFeatures
                                QString additionalFileExtensions() const;
                                QString displayName() const;
                                QString description() const;
                                const PixmapLoader* logo() const;
                        } ;
 
                        using KeyList = QList<Key>;
 
                        SubPluginFeatures( Plugin::Type type ) :
                                m_type( type )
                        {
                        }
 
                        virtual ~SubPluginFeatures() = default;
 
                        virtual void fillDescriptionWidget( QWidget *, const Key * ) const
                        {
                        }

                        virtual void listSubPluginKeys( const Plugin::Descriptor *, KeyList & ) const
                        {
                        }
 
 
                private:
                        // You can add values mapped by "Key" below
                        // The defaults are sane, i.e. redirect to sub plugin's
                        // supererior descriptor
 
                        virtual QString additionalFileExtensions(const Key&) const
                        {
                                return QString();
                        }
 
                        virtual QString displayName(const Key& k) const
                        {
                                return k.isValid() ? k.name : QString();
                        }
 
                        virtual QString description(const Key& k) const
                        {
                                return k.isValid() ? k.desc->description : QString();
                        }
 
                        virtual const PixmapLoader* logo(const Key& k) const
                        {
                                Q_ASSERT(k.desc);
                                return k.desc->logo;
                        }
 
                protected:
                        const Plugin::Type m_type;
                } ;
 
                SubPluginFeatures * subPluginFeatures;
 
        } ;
        // typedef a list so we can easily work with list of plugin descriptors
        using DescriptorList = QList<Descriptor*>;

        Plugin(const Descriptor * descriptor, Model * parent,
                const Descriptor::SubPluginFeatures::Key *key = nullptr);
        ~Plugin() override = default;

        QString displayName() const override;

        const PixmapLoader *logo() const;

        inline Type type() const
        {
                return m_descriptor->type;
        }

        inline const Descriptor * descriptor() const
        {
                return m_descriptor;
        }

        inline const Descriptor::SubPluginFeatures::Key & key() const
        {
                return m_key;
        }

        virtual void loadFile( const QString & file );

        virtual AutomatableModel* childModel( const QString & modelName );

        static Plugin * instantiateWithKey(const QString& pluginName, Model * parent,
                                        const Descriptor::SubPluginFeatures::Key *key,
                                        bool keyFromDnd = false);

        static Plugin * instantiate(const QString& pluginName, Model * parent, void *data);

        gui::PluginView * createView( QWidget * parent );
 
protected:
        virtual gui::PluginView* instantiateView( QWidget * ) = 0;
        void collectErrorForUI( QString errMsg );
 
 
private:
        const Descriptor * m_descriptor;
 
        Descriptor::SubPluginFeatures::Key m_key;
 
        // pointer to instantiation-function in plugin
        using InstantiationHook = Plugin* (*)(Model*, void*);
} ;
 
 
} // namespace lmms
 
#endif // LMMS_PLUGIN_H