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 );

    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