src/engines/InstrumentEditor.h

/***************************************************************************
 *                                                                         *
 *   Copyright (C) 2007 Christian Schoenebeck                              *
 *                                                                         *
 *   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; if not, write to the Free Software           *
 *   Foundation, Inc., 59 Temple Place, Suite 330, Boston,                 *
 *   MA  02111-1307  USA                                                   *
 ***************************************************************************/

#ifndef LS_INSTRUMENT_EDITOR_H
#define LS_INSTRUMENT_EDITOR_H

#include "../common/global.h"
#include "../common/Thread.h"

#include <set>

namespace LinuxSampler {

    // just symbol prototyping
    class InstrumentEditorListener;

    /** @brief Instrument Editor Interface (external plugin)
     *
     * LinuxSampler allows to spawn arbitrary instrument editor applications
     * within the sampler's own process. That way instrument editors are
     * able to modify already loaded instruments live or on-the-fly, that is
     * without having to load it again neither on sampler nor on editor side,
     * which is essential for editing large instruments.
     *
     * Instrument editors have to implement this abstract base class, embedded
     * into a DLL and placed into the respective sampler's library path. The
     * sampler will load these external DLLs as plugins on startup. Whenever
     * there's a request for editing an instrument, the sampler will try to
     * launch a matching registered editor, by calling the respective
     * plugin's Main() method.
     */
    class InstrumentEditor : protected Thread {
    public:

        /////////////////////////////////////////////////////////////////
        // abstract methods
        //     (these have to be implemented by the descendant)

        /**
         * Entry point for the instrument editor's thread. As the
         * instrument data structure is passed as typeless (void*)
         * pointer, this is not type safe! The implementing instrument
         * editor has to interpret the @a sTypeName and @a sTypeVersion
         * arguments to determine if it's able to cast the instrument
         * pointer to a known type and actually be able to work with it.
         *
         * @param pInstrument - pointer to the respective instrument object
         * @param sTypeName - format of the instrument data structure
         *                    (i.e. "libgig")
         * @param sTypeVersion - version of the instrument data structure
         *                       (i.e. "3.0.1").
         */
        virtual int Main(void* pInstrument, String sTypeName, String sTypeVersion) = 0;

        /**
         * The instrument editor has to return @c true in case it supports
         * the given instrument data structure type and version, it has to
         * return @c false otherwise. This method will be called by the
         * sampler to determine which editor is capable to work with a
         * certain instrument.
         *
         * @param sTypeName - i.e. "libgig"
         * @param STypeVersion - i.e. "3.0.1"
         */
        virtual bool IsTypeSupported(String sTypeName, String sTypeVersion) = 0;

        /**
         * The instrument editor's name (i.e. "gigedit").
         */
        virtual String Name() = 0;

        /**
         * The instrument editor's version (i.e. "0.0.1").
         */
        virtual String Version() = 0;

        /**
         * Arbitrary textual description of the instrument editor
         * (i.e. "Gigasampler and DLS format editor, GTK based").
         */
        virtual String Description() = 0;


        /////////////////////////////////////////////////////////////////
        // normal methods
        //     (usually not to be overriden by descendant)

        /**
         * Launch the instrument editor for the given instrument. The
         * editor will be spawned in its own thread and this method will
         * return as soon as the editor's thread actually started.
         */
        void Launch(void* pInstrument, String sTypeName, String sTypeVersion);

        /**
         * Registers object that wants to be notified on events.
         */
        void AddListener(InstrumentEditorListener* pListener);

        /**
         * Unregisters object that doesn't want to be notified anymore.
         */
        void RemoveListener(InstrumentEditorListener* pListener);

        /**
         * Constructor
         */
        InstrumentEditor();

    protected:
        std::set<InstrumentEditorListener*> listeners;

        // derived abstract method from base class 'Thread'
        virtual int Main();
    private:
        void*    pInstrument;
        String   sTypeName;
        String   sTypeVersion;
    };

    /** @brief Instrument Editor Notifications
     *
     * This abstract interface class has to be implemented by classes that
     * want to be notified on certain events of an instrument editor.
     */
    class InstrumentEditorListener {
    public:
        /// Called after the instrument editor stopped running.
        virtual void OnInstrumentEditorQuit(InstrumentEditor* pSender) = 0;
    };

} // namespace LinuxSampler

#endif // LS_INSTRUMENT_EDITOR_H
1	/***************************************************************************
2	* *
3	* Copyright (C) 2007 Christian Schoenebeck *
4	* *
5	* This program is free software; you can redistribute it and/or modify *
6	* it under the terms of the GNU General Public License as published by *
7	* the Free Software Foundation; either version 2 of the License, or *
8	* (at your option) any later version. *
9	* *
10	* This program is distributed in the hope that it will be useful, *
11	* but WITHOUT ANY WARRANTY; without even the implied warranty of *
12	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13	* GNU General Public License for more details. *
14	* *
15	* You should have received a copy of the GNU General Public License *
16	* along with this program; if not, write to the Free Software *
17	* Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
18	* MA 02111-1307 USA *
19	***************************************************************************/
20
21	#ifndef LS_INSTRUMENT_EDITOR_H
22	#define LS_INSTRUMENT_EDITOR_H
23
24	#include "../common/global.h"
25	#include "../common/Thread.h"
26
27	#include <set>
28
29	namespace LinuxSampler {
30
31	// just symbol prototyping
32	class InstrumentEditorListener;
33
34	/** @brief Instrument Editor Interface (external plugin)
35	*
36	* LinuxSampler allows to spawn arbitrary instrument editor applications
37	* within the sampler's own process. That way instrument editors are
38	* able to modify already loaded instruments live or on-the-fly, that is
39	* without having to load it again neither on sampler nor on editor side,
40	* which is essential for editing large instruments.
41	*
42	* Instrument editors have to implement this abstract base class, embedded
43	* into a DLL and placed into the respective sampler's library path. The
44	* sampler will load these external DLLs as plugins on startup. Whenever
45	* there's a request for editing an instrument, the sampler will try to
46	* launch a matching registered editor, by calling the respective
47	* plugin's Main() method.
48	*/
49	class InstrumentEditor : protected Thread {
50	public:
51
52	/////////////////////////////////////////////////////////////////
53	// abstract methods
54	// (these have to be implemented by the descendant)
55
56	/**
57	* Entry point for the instrument editor's thread. As the
58	* instrument data structure is passed as typeless (void*)
59	* pointer, this is not type safe! The implementing instrument
60	* editor has to interpret the @a sTypeName and @a sTypeVersion
61	* arguments to determine if it's able to cast the instrument
62	* pointer to a known type and actually be able to work with it.
63	*
64	* @param pInstrument - pointer to the respective instrument object
65	* @param sTypeName - format of the instrument data structure
66	* (i.e. "libgig")
67	* @param sTypeVersion - version of the instrument data structure
68	* (i.e. "3.0.1").
69	*/
70	virtual int Main(void* pInstrument, String sTypeName, String sTypeVersion) = 0;
71
72	/**
73	* The instrument editor has to return @c true in case it supports
74	* the given instrument data structure type and version, it has to
75	* return @c false otherwise. This method will be called by the
76	* sampler to determine which editor is capable to work with a
77	* certain instrument.
78	*
79	* @param sTypeName - i.e. "libgig"
80	* @param STypeVersion - i.e. "3.0.1"
81	*/
82	virtual bool IsTypeSupported(String sTypeName, String sTypeVersion) = 0;
83
84	/**
85	* The instrument editor's name (i.e. "gigedit").
86	*/
87	virtual String Name() = 0;
88
89	/**
90	* The instrument editor's version (i.e. "0.0.1").
91	*/
92	virtual String Version() = 0;
93
94	/**
95	* Arbitrary textual description of the instrument editor
96	* (i.e. "Gigasampler and DLS format editor, GTK based").
97	*/
98	virtual String Description() = 0;
99
100
101
102	/////////////////////////////////////////////////////////////////
103	// normal methods
104	// (usually not to be overriden by descendant)
105
106	/**
107	* Launch the instrument editor for the given instrument. The
108	* editor will be spawned in its own thread and this method will
109	* return as soon as the editor's thread actually started.
110	*/
111	void Launch(void* pInstrument, String sTypeName, String sTypeVersion);
112
113	/**
114	* Registers object that wants to be notified on events.
115	*/
116	void AddListener(InstrumentEditorListener* pListener);
117
118	/**
119	* Unregisters object that doesn't want to be notified anymore.
120	*/
121	void RemoveListener(InstrumentEditorListener* pListener);
122
123	/**
124	* Constructor
125	*/
126	InstrumentEditor();
127
128	protected:
129	std::set<InstrumentEditorListener*> listeners;
130
131	// derived abstract method from base class 'Thread'
132	virtual int Main();
133	private:
134	void* pInstrument;
135	String sTypeName;
136	String sTypeVersion;
137	};
138
139	/** @brief Instrument Editor Notifications
140	*
141	* This abstract interface class has to be implemented by classes that
142	* want to be notified on certain events of an instrument editor.
143	*/
144	class InstrumentEditorListener {
145	public:
146	/// Called after the instrument editor stopped running.
147	virtual void OnInstrumentEditorQuit(InstrumentEditor* pSender) = 0;
148	};
149
150	} // namespace LinuxSampler
151
152	#endif // LS_INSTRUMENT_EDITOR_H