Plugin API: add an ability to append parts to a score

src/libmscore/score.cpp

@@ -3972,27 +3972,8 @@ bool Score::switchLayer(const QString& s)
 //   appendPart
 //---------------------------------------------------------
 
-void Score::appendPart(const QString& name)
+void Score::appendPart(const InstrumentTemplate* t)
 {
-    static InstrumentTemplate defaultInstrument;
-    InstrumentTemplate* t;
-
-    t = searchTemplate(name);
-    if (t == 0) {
-        qDebug("appendPart: <%s> not found", qPrintable(name));
-        t = &defaultInstrument;
-    }
-
-    if (t->channel.empty()) {
-        Channel a;
-        a.setChorus(0);
-        a.setReverb(0);
-        a.setName(Channel::DEFAULT_NAME);
-        a.setBank(0);
-        a.setVolume(90);
-        a.setPan(0);
-        t->channel.append(a);
-    }
     Part* part = new Part(this);
     part->initFromInstrTemplate(t);
     int n = nstaves();

src/libmscore/score.h

@@ -830,6 +830,7 @@ public:
     const QList<Part*>& parts() const { return _parts; }
 
     void appendPart(Part* p);
+    void appendPart(const InstrumentTemplate*);
     void updateStaffIndex();
     void sortStaves(QList<int>& dst);
 
@@ -1200,8 +1201,6 @@ public:
 
     QList<Score*> scoreList();
     bool switchLayer(const QString& s);
-    //@ appends to the score a named part as last part
-    void appendPart(const QString&);
     //@ appends to the score a number of measures
     void appendMeasures(int);
 

src/plugins/api/part.h

@@ -27,7 +27,13 @@ class Part : public Ms::PluginAPI::ScoreElement
     Q_OBJECT
     Q_PROPERTY(int startTrack READ startTrack)
     Q_PROPERTY(int endTrack READ endTrack)
-    /// The string identifier for the current instrument. \since MuseScore 3.2
+    /**
+     * The string identifier
+     * ([MusicXML Sound ID](https://www.musicxml.com/for-developers/standard-sounds/))
+     * for the first instrument in this part.
+     * \see \ref Ms::PluginAPI::Instrument::instrumentId "Instrument.instrumentId"
+     * \since MuseScore 3.2
+     */
     Q_PROPERTY(QString instrumentId READ instrumentId)
     /// The number of Chord Symbols. \since MuseScore 3.2.1
     Q_PROPERTY(int harmonyCount READ harmonyCount)

src/plugins/api/qmlpluginapi.cpp

@@ -215,7 +215,7 @@ Score* PluginAPI::newScore(const QString& name, const QString& part, int measure
     }
     MasterScore* score = new MasterScore(MScore::defaultStyle());
     score->setName(name);
-    score->appendPart(part);
+    score->appendPart(Score::instrTemplateFromName(part));
     score->appendMeasures(measures);
     score->doLayout();
     const int view = msc()->appendScore(score);

src/plugins/api/score.cpp

@@ -13,6 +13,7 @@
 #include "score.h"
 #include "cursor.h"
 #include "elements.h"
+#include "libmscore/instrtemplate.h"
 #include "libmscore/measure.h"
 #include "libmscore/score.h"
 #include "libmscore/segment.h"
@@ -65,6 +66,72 @@ void Score::addText(const QString& type, const QString& txt)
     score()->undoAddElement(text);
 }
 
+//---------------------------------------------------------
+//   defaultInstrTemplate
+//---------------------------------------------------------
+
+static const InstrumentTemplate* defaultInstrTemplate()
+{
+    static InstrumentTemplate defaultInstrument;
+    if (defaultInstrument.channel.empty()) {
+        Channel a;
+        a.setChorus(0);
+        a.setReverb(0);
+        a.setName(Channel::DEFAULT_NAME);
+        a.setBank(0);
+        a.setVolume(90);
+        a.setPan(0);
+        defaultInstrument.channel.append(a);
+    }
+    return &defaultInstrument;
+}
+
+//---------------------------------------------------------
+//   instrTemplateFromName
+//---------------------------------------------------------
+
+const InstrumentTemplate* Score::instrTemplateFromName(const QString& name)
+{
+    const InstrumentTemplate* t = searchTemplate(name);
+    if (!t) {
+        qWarning("<%s> not found", qPrintable(name));
+        t = defaultInstrTemplate();
+    }
+    return t;
+}
+
+//---------------------------------------------------------
+//   Score::appendPart
+//---------------------------------------------------------
+
+void Score::appendPart(const QString& instrumentId)
+{
+    const InstrumentTemplate* t = searchTemplate(instrumentId);
+
+    if (!t) {
+        qWarning("appendPart: <%s> not found", qPrintable(instrumentId));
+        t = defaultInstrTemplate();
+    }
+
+    score()->appendPart(t);
+}
+
+//---------------------------------------------------------
+//   Score::appendPartByMusicXmlId
+//---------------------------------------------------------
+
+void Score::appendPartByMusicXmlId(const QString& instrumentMusicXmlId)
+{
+    const InstrumentTemplate* t = searchTemplateForMusicXmlId(instrumentMusicXmlId);
+
+    if (!t) {
+        qWarning("appendPart: <%s> not found", qPrintable(instrumentMusicXmlId));
+        t = defaultInstrTemplate();
+    }
+
+    score()->appendPart(t);
+}
+
 //---------------------------------------------------------
 //   Score::firstSegment
 //---------------------------------------------------------

src/plugins/api/score.h

@@ -20,6 +20,8 @@
 #include "libmscore/score.h"
 
 namespace Ms {
+class InstrumentTemplate;
+
 namespace PluginAPI {
 class Cursor;
 class Segment;
@@ -129,8 +131,26 @@ public:
     /// Sets the metatag named \p tag to \p val
     Q_INVOKABLE void setMetaTag(const QString& tag, const QString& val) { score()->setMetaTag(tag, val); }
 
-//      //@ appends to the score a named part as last part
-//      Q_INVOKABLE void appendPart(const QString&);
+    /**
+     * Appends a part with the instrument defined by \p instrumentId
+     * to this score.
+     * \param instrumentId - ID of the instrument to be added, as listed in
+     * [`instruments.xml`](https://github.com/musescore/MuseScore/blob/3.x/share/instruments/instruments.xml)
+     * file.
+     * \since MuseScore 3.5
+     */
+    Q_INVOKABLE void appendPart(const QString& instrumentId);
+    /**
+     * Appends a part with the instrument defined by the given MusicXML ID
+     * to this score.
+     * \param instrumentMusicXmlId -
+     * [MusicXML Sound ID](https://www.musicxml.com/for-developers/standard-sounds/)
+     * of the instrument to be added.
+     * \see \ref Ms::PluginAPI::Part::instrumentId, \ref Ms::PluginAPI::Instrument::instrumentId
+     * \since MuseScore 3.5
+     */
+    Q_INVOKABLE void appendPartByMusicXmlId(const QString& instrumentMusicXmlId);
+
     /// Appends a number of measures to this score.
     Q_INVOKABLE void appendMeasures(int n) { score()->appendMeasures(n); }
     Q_INVOKABLE void addText(const QString& type, const QString& text);
@@ -197,6 +217,8 @@ public:
 
     QQmlListProperty<Part> parts() { return wrapContainerProperty<Part>(this, score()->parts()); }
     QQmlListProperty<Excerpt> excerpts() { return wrapExcerptsContainerProperty<Excerpt>(this, score()->excerpts()); }
+
+    static const Ms::InstrumentTemplate* instrTemplateFromName(const QString& name);   // used by PluginAPI::newScore()
     /// \endcond
 };
 } // namespace PluginAPI