Line data Source code
1 : /*
2 : * SPDX-License-Identifier: GPL-3.0-only
3 : * MuseScore-Studio-CLA-applies
4 : *
5 : * MuseScore Studio
6 : * Music Composition & Notation
7 : *
8 : * Copyright (C) 2021 MuseScore Limited and others
9 : *
10 : * This program is free software: you can redistribute it and/or modify
11 : * it under the terms of the GNU General Public License version 3 as
12 : * published by the Free Software Foundation.
13 : *
14 : * This program is distributed in the hope that it will be useful,
15 : * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 : * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 : * GNU General Public License for more details.
18 : *
19 : * You should have received a copy of the GNU General Public License
20 : * along with this program. If not, see <https://www.gnu.org/licenses/>.
21 : */
22 :
23 : #pragma once
24 :
25 : #include "scoreelement.h"
26 :
27 : #include "modularity/ioc.h"
28 : #include "project/iprojectsession.h"
29 :
30 : #include "engraving/dom/score.h"
31 : #include "engraving/dom/segment.h"
32 :
33 : // api
34 : #include "excerpt.h"
35 : #include "apistructs.h"
36 : #include "style.h"
37 : #include "part.h"
38 : #include "excerpt.h"
39 :
40 : Q_MOC_INCLUDE("engraving/api/v1/selection.h")
41 :
42 : namespace mu::engraving {
43 : class InstrumentTemplate;
44 : class Selection;
45 : }
46 :
47 : namespace mu::engraving::apiv1 {
48 : class Cursor;
49 : class Segment;
50 : class Measure;
51 : class Page;
52 : class MeasureBase;
53 : class System;
54 : class Selection;
55 : class Score;
56 : class Staff;
57 : class Drumset;
58 : class Lyrics;
59 : class Spanner;
60 :
61 : extern Selection* selectionWrap(mu::engraving::Selection* select);
62 :
63 : //---------------------------------------------------------
64 : // Score
65 : //---------------------------------------------------------
66 : /** APIDOC
67 : * Class representing a score.
68 : * We can get the current score by calling the `Engraving.curScore`
69 : * @class Score
70 : * @memberof Engraving
71 : * @hideconstructor
72 : */
73 : class Score : public apiv1::ScoreElement, public muse::Contextable
74 : {
75 : Q_OBJECT
76 :
77 : /** APIDOC
78 : * Name of the score, without path leading to it and extension.
79 : * @q_property {String}
80 : */
81 : Q_PROPERTY(QString scoreName READ name WRITE setName)
82 :
83 : /** APIDOC
84 : * Title of score, as taken from the score properties `workTitle`
85 : * @readonly
86 : * @q_property {String}
87 : */
88 : Q_PROPERTY(QString title READ title)
89 :
90 : /** APIDOC
91 : * Composer of the score, as taken from the score properties
92 : * @readonly
93 : * @q_property {String}
94 : */
95 : Q_PROPERTY(QString composer READ composer)
96 :
97 : /** APIDOC
98 : * Lyricist of score, as taken from the score properties.
99 : * @readonly
100 : * @q_property {String}
101 : */
102 : Q_PROPERTY(QString lyricist READ lyricist)
103 :
104 : /** APIDOC
105 : * Duration of score in seconds
106 : * @readonly
107 : * @q_property {Number}
108 : */
109 : Q_PROPERTY(int duration READ duration)
110 :
111 : /** APIDOC
112 : * MuseScore version the score has been last saved with (includes autosave)
113 : * @readonly
114 : * @q_property {String}
115 : */
116 : Q_PROPERTY(QString mscoreVersion READ mscoreVersion)
117 :
118 : /** APIDOC
119 : * MuseScore revision the score has been last saved with (includes autosave)
120 : * @readonly
121 : * @q_property {String}
122 : */
123 : Q_PROPERTY(QString mscoreRevision READ mscoreRevision)
124 :
125 : /** APIDOC
126 : * Style settings for this score.
127 : * @readonly
128 : * @q_property {Engraving.Style}
129 : */
130 : Q_PROPERTY(apiv1::MStyle * style READ style)
131 :
132 : /** APIDOC
133 : * Key signature at the start of the score, in number of accidentals,
134 : * negative for flats, positive for sharps
135 : * @readonly
136 : * @q_property {Number}
137 : */
138 : Q_PROPERTY(int keysig READ keysig)
139 :
140 : /** APIDOC
141 : * Number of pages
142 : * @readonly
143 : * @q_property {Number}
144 : */
145 : Q_PROPERTY(int npages READ npages)
146 :
147 : /** APIDOC
148 : * List of pages in this score.
149 : * @readonly
150 : * @q_property {Engraving.Page[]}
151 : * @since 4.6
152 : */
153 : Q_PROPERTY(QQmlListProperty<apiv1::Page> pages READ pages)
154 :
155 : /** APIDOC
156 : * Page numbering offset. The user-visible number of the given page is defined as
157 : * ```
158 : * page.pagenumber + 1 + score.pageNumberOffset
159 : * ```
160 : * @q_property {Number}
161 : */
162 : Q_PROPERTY(int pageNumberOffset READ pageNumberOffset WRITE setPageNumberOffset)
163 :
164 : /** APIDOC
165 : * The list of parts
166 : * @readonly
167 : * @q_property {Engraving.Part[]}
168 : */
169 : Q_PROPERTY(QQmlListProperty<apiv1::Part> parts READ parts)
170 :
171 : /** APIDOC
172 : * Number of staves
173 : * @readonly
174 : * @q_property {Number}
175 : */
176 : Q_PROPERTY(int nstaves READ nstaves)
177 :
178 : /** APIDOC
179 : * List of staves in this score.
180 : * @readonly
181 : * @q_property {Engraving.Staff[]}
182 : */
183 : Q_PROPERTY(QQmlListProperty<apiv1::Staff> staves READ staves)
184 :
185 : /** APIDOC
186 : * Number of tracks
187 : * @readonly
188 : * @q_property {Number}
189 : */
190 : Q_PROPERTY(int ntracks READ ntracks)
191 :
192 : /** APIDOC
193 : * List of systems in this score.
194 : * @readonly
195 : * @q_property {Engraving.System[]}
196 : * @since 4.6
197 : */
198 : Q_PROPERTY(QQmlListProperty<apiv1::System> systems READ systems)
199 :
200 : /** APIDOC
201 : * List of spanners (hairpins, slurs, etc.) in this score.
202 : * @readonly
203 : * @q_property {Engraving.Spanner[]}
204 : * @since 4.7
205 : */
206 : Q_PROPERTY(QQmlListProperty<apiv1::Spanner> spanners READ spanners)
207 :
208 : /** APIDOC
209 : * Whether score has harmonies (chord symbols)
210 : * @readonly
211 : * @q_property {Boolean}
212 : */
213 : Q_PROPERTY(bool hasHarmonies READ hasHarmonies)
214 :
215 : /** APIDOC
216 : * Number of harmony items (chord symbols) in the score
217 : * @readonly
218 : * @q_property {Number}
219 : */
220 : Q_PROPERTY(int harmonyCount READ harmonyCount)
221 :
222 : /** APIDOC
223 : * Whether score has lyrics
224 : * @readonly
225 : * @q_property {Boolean}
226 : */
227 : Q_PROPERTY(bool hasLyrics READ hasLyrics)
228 :
229 : /** APIDOC
230 : * Number of lyrics items (syllables) in the score
231 : * @readonly
232 : * @q_property {Number}
233 : */
234 : Q_PROPERTY(int lyricCount READ lyricCount)
235 :
236 : /** APIDOC
237 : * List of lyrics in this score.
238 : * @readonly
239 : * @q_property {Engraving.Lyrics[]}
240 : * @since 4.7
241 : */
242 : Q_PROPERTY(QQmlListProperty<apiv1::Lyrics> lyrics READ lyrics)
243 :
244 : /** APIDOC
245 : * Number of measures
246 : * @readonly
247 : * @q_property {Number}
248 : */
249 : Q_PROPERTY(int nmeasures READ nmeasures)
250 :
251 : /** APIDOC
252 : * First measure of the score
253 : * @readonly
254 : * @q_property {Engraving.Measure}
255 : */
256 : Q_PROPERTY(apiv1::Measure * firstMeasure READ firstMeasure)
257 :
258 : /** APIDOC
259 : * First multimeasure rest measure of the score
260 : * @readonly
261 : * @q_property {Engraving.Measure}
262 : * @see Engraving.Measure.nextMeasureMM
263 : */
264 : Q_PROPERTY(apiv1::Measure * firstMeasureMM READ firstMeasureMM)
265 :
266 : /** APIDOC
267 : * Last measure of the score
268 : * @readonly
269 : * @q_property {Engraving.Measure}
270 : */
271 : Q_PROPERTY(apiv1::Measure * lastMeasure READ lastMeasure)
272 :
273 : /** APIDOC
274 : * Last multimeasure rest measure of the score
275 : * @readonly
276 : * @q_property {Engraving.Measure}
277 : * @see Engraving.Measure.prevMeasureMM
278 : */
279 : Q_PROPERTY(apiv1::Measure * lastMeasureMM READ lastMeasureMM)
280 :
281 : /** APIDOC
282 : * Last score segment
283 : * @readonly
284 : * @q_property {Engraving.Segment}
285 : */
286 : Q_PROPERTY(apiv1::Segment * lastSegment READ lastSegment) // TODO: make it function? Was property in 2.X, but firstSegment is a function...
287 :
288 : /** APIDOC
289 : * The current layout mode, a PluginAPI::LayoutMode value.
290 : * @q_property {Number}
291 : * @since 4.6
292 : */
293 : Q_PROPERTY(int layoutMode READ layoutMode WRITE setLayoutMode)
294 :
295 : /** APIDOC
296 : * Whether vertical frames are visible in the current layout mode.
297 : * @q_property {Boolean}
298 : * @since 4.6
299 : */
300 : Q_PROPERTY(bool showVerticalFrames READ isShowVBox WRITE setShowVBox)
301 :
302 : /** APIDOC
303 : * Whether invisible elements are shown in the score.
304 : * @q_property {Boolean}
305 : * @since 4.6
306 : */
307 : Q_PROPERTY(bool showInvisible READ isShowInvisible WRITE setShowInvisible)
308 :
309 : /** APIDOC
310 : * Whether formatting elements are displayed in the score.
311 : * @q_property {Boolean}
312 : * @since 4.6
313 : */
314 : Q_PROPERTY(bool showUnprintable READ showUnprintable WRITE setShowUnprintable)
315 :
316 : /** APIDOC
317 : * Whether frames are displayed in the score.
318 : * @q_property {Boolean}
319 : * @since 4.6
320 : */
321 : Q_PROPERTY(bool showFrames READ showFrames WRITE setShowFrames)
322 :
323 : /** APIDOC
324 : * Whether page borders are displayed in the score.
325 : * @q_property {Boolean}
326 : * @since 4.6
327 : */
328 : Q_PROPERTY(bool showPageborders READ showPageborders WRITE setShowPageborders)
329 :
330 : /** APIDOC
331 : * Whether sound flags are displayed in the score.
332 : * @q_property {Boolean}
333 : * @since 4.6
334 : */
335 : Q_PROPERTY(bool showSoundFlags READ showSoundFlags WRITE setShowSoundFlags)
336 :
337 : /** APIDOC
338 : * Whether corrupted measures are marked in the score.
339 : * @q_property {Boolean}
340 : * @since 4.6
341 : */
342 : Q_PROPERTY(bool markIrregularMeasures READ markIrregularMeasures WRITE setMarkIrregularMeasures)
343 :
344 : /** APIDOC
345 : * Whether instrument names are displayed
346 : * @q_property {Boolean}
347 : * @since 4.6
348 : */
349 : Q_PROPERTY(bool showInstrumentNames READ showInstrumentNames WRITE setShowInstrumentNames)
350 :
351 : /** APIDOC
352 : * Current selections for the score.
353 : * @readonly
354 : * @q_property {Engraving.Selection}
355 : */
356 : Q_PROPERTY(apiv1::Selection * selection READ selection)
357 :
358 : /** APIDOC
359 : * List of the excerpts (linked parts)
360 : * @readonly
361 : * @q_property {Engraving.Excerpt[]}
362 : */
363 : Q_PROPERTY(QQmlListProperty<apiv1::Excerpt> excerpts READ excerpts)
364 :
365 : muse::ContextInject<mu::project::IProjectSession> projectSession = { this };
366 :
367 : public:
368 16 : Score(mu::engraving::Score* s, Ownership o = Ownership::SCORE)
369 16 : : ScoreElement(s, o), muse::Contextable(s->iocContext()) {}
370 :
371 : QString name() const;
372 : void setName(const QString& name);
373 0 : QString title() const { return score()->metaTag(u"workTitle"); }
374 0 : QString composer() const { return score()->metaTag(u"composer"); }
375 0 : QString lyricist() const { return score()->metaTag(u"lyricist"); } // not the meanwhile obsolete "poet"
376 : /** APIDOC
377 : * Get the value of a meta tag by name
378 : * @method
379 : * @param {String} tag Tag
380 : * @return {String} Tag value
381 : */
382 0 : Q_INVOKABLE QString metaTag(const QString& tag) const { return score()->metaTag(tag); }
383 : /** APIDOC
384 : * Set a value of a meta tag by name
385 : * @method
386 : * @param {String} tag Tag
387 : * @param {String} value Value
388 : */
389 0 : Q_INVOKABLE void setMetaTag(const QString& tag, const QString& val) { score()->setMetaTag(tag, val); }
390 :
391 0 : int duration() const { return score()->duration(); }
392 0 : QString mscoreVersion() const { return score()->mscoreVersion(); }
393 0 : QString mscoreRevision() const { return QString::number(score()->mscoreRevision(), /* base */ 16); }
394 0 : apiv1::MStyle* style() { return styleWrap(&score()->style(), score()); }
395 :
396 0 : int keysig() const { return score()->keysig(); }
397 :
398 0 : int npages() const { return static_cast<int>(score()->npages()); }
399 : QQmlListProperty<apiv1::Page> pages() const;
400 0 : int pageNumberOffset() const { return score()->pageNumberOffset(); }
401 0 : void setPageNumberOffset(int offset) { score()->undoChangePageNumberOffset(offset); }
402 :
403 : QQmlListProperty<apiv1::Part> parts() const;
404 : /** APIDOC
405 : * Appends a part with the instrument defined by `instrumentId` to this score.
406 : * @method
407 : * @param {String} instrumentId ID of the instrument to be added,
408 : * as listed in {@link https://github.com/musescore/MuseScore/blob/master/share/instruments/instruments.xml|instruments.xml}
409 : */
410 : Q_INVOKABLE void appendPart(const QString& instrumentId);
411 : /** APIDOC
412 : * Appends a part with the instrument defined by the given MusicXML ID to this score.
413 : * @method
414 : * @param {String} instrumentMusicXmlId {@link https://www.musicxml.com/for-developers/standard-sounds/|MusicXML Sound ID}
415 : * of the instrument to be added.
416 : */
417 : Q_INVOKABLE void appendPartByMusicXmlId(const QString& instrumentMusicXmlId);
418 :
419 0 : int nstaves() const { return static_cast<int>(score()->nstaves()); }
420 : QQmlListProperty<apiv1::Staff> staves() const;
421 :
422 0 : int ntracks() const { return static_cast<int>(score()->ntracks()); }
423 :
424 : QQmlListProperty<apiv1::System> systems() const;
425 : /** APIDOC
426 : * Add or remove system locks to the current selection.
427 : * @method
428 : * @param {Number} interval Specifies after how many measures locks should be added.
429 : * @param {boolean} lock If `true`, adds locks, else removes them.
430 : * @since 4.6
431 : */
432 : Q_INVOKABLE void addRemoveSystemLocks(int interval, bool lock);
433 :
434 : /** APIDOC
435 : * Create a (locked) system from two {@link Engraving.Measure} objects.
436 : * @method
437 : * @param {Engraving.Measure} first The first `Measure` in the system.
438 : * @param {Engraving.Measure} last The last `Measure` in the system.
439 : * @since 4.6
440 : */
441 : Q_INVOKABLE void makeIntoSystem(apiv1::MeasureBase* first, apiv1::MeasureBase* last);
442 :
443 : /** APIDOC
444 : * List of bracket items for staffIdx
445 : * @method
446 : * @param {Number} staffIdx Staff index
447 : * @since 5.0
448 : */
449 : Q_INVOKABLE QQmlListProperty<EngravingItem> brackets(int staffIdx);
450 :
451 : QQmlListProperty<apiv1::Spanner> spanners();
452 :
453 0 : int harmonyCount() const { return score()->harmonyCount(); }
454 0 : bool hasHarmonies() const { return score()->hasHarmonies(); }
455 :
456 : bool hasLyrics() const;
457 : int lyricCount() const;
458 : QQmlListProperty<apiv1::Lyrics> lyrics() const;
459 : /** APIDOC
460 : * Extracts all lyrics in the score and returns them in a single string.
461 : * @method
462 : * @return {String} lyrics string
463 : */
464 : Q_INVOKABLE QString extractLyrics() const;
465 :
466 0 : int nmeasures() const { return static_cast<int>(score()->nmeasures()); }
467 : Measure* firstMeasure();
468 : Measure* firstMeasureMM();
469 : Measure* lastMeasure();
470 : Measure* lastMeasureMM();
471 : /** APIDOC
472 : * Appends a number of measures to this score.
473 : * @method
474 : * @param {Number} n number of measures
475 : */
476 0 : Q_INVOKABLE void appendMeasures(int n) { score()->appendMeasures(n); }
477 : /** APIDOC
478 : * The measure at a given tick in the score.
479 : * @method
480 : * @param {Engraving.Fraction} tick Tick to search for the measure
481 : * @since 4.6
482 : */
483 : Q_INVOKABLE apiv1::Measure* tick2measure(apiv1::Fraction* tick);
484 :
485 : /** APIDOC
486 : * The first segment of a given type in the score.
487 : * Before MuseScore 4.6, the type could not be specified.
488 : * @method
489 : * @param {Number} segmentType If not specified, defaults to all types.
490 : * @return {Engraving.Segment} Segment object
491 : */
492 : Q_INVOKABLE apiv1::Segment* firstSegment(int segmentType = int(mu::engraving::SegmentType::All));
493 :
494 : /** APIDOC
495 : * Looks for a segment of a given type at a given tick.
496 : * Does not create a segment or modify the score.
497 : * @method
498 : * @param {Number} types Determines the types of segments to look for.
499 : * @param {Engraving.Fraction} tick Determines where to look for the segment
500 : * @return {Engraving.Segment} Segment object
501 : * @since 4.6
502 : */
503 : Q_INVOKABLE apiv1::Segment* findSegmentAtTick(int types, apiv1::Fraction* tick);
504 :
505 : /** APIDOC
506 : * Add the text
507 : * @method
508 : * @param {Engraving.TextStyleType} type Stype type of text
509 : * @param {String} text Value of text
510 : */
511 : Q_INVOKABLE void addText(const QString& type, const QString& text);
512 :
513 0 : int layoutMode() { return int(score()->layoutMode()); }
514 0 : void setLayoutMode(int mode) { score()->setLayoutMode(mu::engraving::LayoutMode(mode)); }
515 0 : bool isShowVBox() const { return score()->layoutOptions().isShowVBox; }
516 0 : void setShowVBox(bool show) { score()->setShowVBox(show); }
517 0 : bool isShowInvisible() { return score()->isShowInvisible(); }
518 0 : void setShowInvisible(bool v) { score()->setShowInvisible(v); }
519 0 : bool showUnprintable() { return score()->showUnprintable(); }
520 0 : void setShowUnprintable(bool v) { score()->setShowUnprintable(v); }
521 0 : bool showFrames() { return score()->showFrames(); }
522 0 : void setShowFrames(bool v) { score()->setShowFrames(v); }
523 0 : bool showPageborders() { return score()->showPageborders(); }
524 0 : void setShowPageborders(bool v) { score()->setShowPageborders(v); }
525 0 : bool showSoundFlags() { return score()->showSoundFlags(); }
526 0 : void setShowSoundFlags(bool v) { score()->setShowSoundFlags(v); }
527 0 : bool markIrregularMeasures() { return score()->markIrregularMeasures(); }
528 0 : void setMarkIrregularMeasures(bool v) { score()->setMarkIrregularMeasures(v); }
529 0 : bool showInstrumentNames() { return score()->showInstrumentNames(); }
530 0 : void setShowInstrumentNames(bool v) { score()->setShowInstrumentNames(v); }
531 :
532 : /** APIDOC
533 : * Force the score to layout itself.
534 : * The score is laid out automatically at the end of a command,
535 : * however this method can be called to layout mid-command.
536 : * Layout the whole score with:
537 : * ```
538 : * curScore.doLayout(fraction(0, 1), fraction(-1, 1))
539 : * ```
540 : * @method
541 : * @param {Engraving.Fraction} startTick Fraction from which to start the layout
542 : * @param {Engraving.Fraction} endTick Fraction at which to end the layout
543 : * @since 4.6
544 : */
545 : Q_INVOKABLE void doLayout(apiv1::Fraction* startTick, apiv1::Fraction* endTick);
546 :
547 : /** APIDOC
548 : * Replaces the instrument for a given part with a new instrument.
549 : * This changes the instrument definition including its name, clef, and sound.
550 : * @method
551 : * @param {Engraving.Part} part The Part object whose instrument should be replaced.
552 : * @param {String} instrumentId ID of the new instrument, as listed in
553 : * {@link https://github.com/musescore/MuseScore/blob/master/share/instruments/instruments.xml|instruments.xml}
554 : * @since 4.7
555 : */
556 : Q_INVOKABLE void replaceInstrument(apiv1::Part* part, const QString& instrumentId);
557 :
558 : /** APIDOC
559 : * Sets the visibility of a part.
560 : * @method
561 : * @param {Engraving.Part} part The Part object.
562 : * @param {Boolean} visible Whether the part should be visible.
563 : * @since 4.7
564 : */
565 : Q_INVOKABLE void setPartVisible(apiv1::Part* part, bool visible);
566 :
567 : /** APIDOC
568 : * Sets the sharp/flat preference for a part's transposition.
569 : * @method
570 : * @param {Engraving.Part} part The Part object.
571 : * @param {Number} sharpFlat 0 = NONE, 1 = SHARPS, 2 = FLATS.
572 : * @since 4.7
573 : */
574 : Q_INVOKABLE void setPartSharpFlat(apiv1::Part* part, int sharpFlat);
575 :
576 : /** APIDOC
577 : * Sets the long instrument name for a part at the given tick position.
578 : * @method
579 : * @param {Engraving.Part} part The Part object.
580 : * @param {Fraction} tick The tick position (use fraction(0, 1) for the beginning).
581 : * @param {String} name The new long instrument name.
582 : * @since 4.7
583 : */
584 : Q_INVOKABLE void setInstrumentName(apiv1::Part* part, apiv1::Fraction* tick, const QString& name);
585 :
586 : /** APIDOC
587 : * Sets the abbreviated instrument name for a part at the given tick position.
588 : * @method
589 : * @param {Engraving.Part} part The Part object.
590 : * @param {Fraction} tick The tick position (use fraction(0, 1) for the beginning).
591 : * @param {String} abbreviature The new abbreviated instrument name.
592 : * @since 4.7
593 : */
594 : Q_INVOKABLE void setInstrumentAbbreviature(apiv1::Part* part, apiv1::Fraction* tick, const QString& abbreviature);
595 :
596 : /** APIDOC
597 : * Sets the staff type for a staff.
598 : * @method
599 : * @param {Engraving.Staff} staff The Staff object.
600 : * @param {Number} staffTypeId The staff type ID (0 = STANDARD, 4 = PERC_DEFAULT, 6 = TAB_DEFAULT, etc.).
601 : * @since 4.7
602 : */
603 : Q_INVOKABLE void setStaffType(apiv1::Staff* staff, int staffTypeId);
604 :
605 : /** APIDOC
606 : * Removes the specified parts from the score.
607 : * @method
608 : * @param {Engraving.Part[]} parts Array of Part objects to remove.
609 : * @since 4.7
610 : */
611 : Q_INVOKABLE void removeParts(QList<apiv1::Part*> parts);
612 :
613 : /** APIDOC
614 : * Removes the specified staves from the score.
615 : * @method
616 : * @param {Engraving.Staff[]} staves Array of Staff objects to remove.
617 : * @since 4.7
618 : */
619 : Q_INVOKABLE void removeStaves(QList<apiv1::Staff*> staves);
620 :
621 : /** APIDOC
622 : * Moves parts to a new position relative to a destination part.
623 : * @method
624 : * @param {Engraving.Part[]} sourceParts Array of Part objects to move.
625 : * @param {Engraving.Part} destinationPart The Part to insert before or after.
626 : * @param {Number} insertMode 0 = BEFORE, 1 = AFTER.
627 : * @since 4.7
628 : */
629 : Q_INVOKABLE void moveParts(QList<apiv1::Part*> sourceParts, apiv1::Part* destinationPart, int insertMode);
630 :
631 : /** APIDOC
632 : * Moves staves to a new position relative to a destination staff.
633 : * All staves must belong to the same part.
634 : * @method
635 : * @param {Engraving.Staff[]} sourceStaves Array of Staff objects to move.
636 : * @param {Engraving.Staff} destinationStaff The Staff to insert before or after.
637 : * @param {Number} insertMode 0 = BEFORE, 1 = AFTER.
638 : * @since 4.7
639 : */
640 : Q_INVOKABLE void moveStaves(QList<apiv1::Staff*> sourceStaves, apiv1::Staff* destinationStaff, int insertMode);
641 :
642 : /** APIDOC
643 : * Adds system objects (rehearsal marks, tempo markings, etc.) to the specified staves.
644 : * @method
645 : * @param {Engraving.Staff[]} staves Array of Staff objects to add system objects to.
646 : * @since 4.7
647 : */
648 : Q_INVOKABLE void addSystemObjects(QList<apiv1::Staff*> staves);
649 :
650 : /** APIDOC
651 : * Removes system objects from the specified staves.
652 : * @method
653 : * @param {Engraving.Staff[]} staves Array of Staff objects to remove system objects from.
654 : * @since 4.7
655 : */
656 : Q_INVOKABLE void removeSystemObjects(QList<apiv1::Staff*> staves);
657 :
658 : /** APIDOC
659 : * Moves system objects from one staff to another.
660 : * @method
661 : * @param {Engraving.Staff} sourceStaff The Staff to move system objects from.
662 : * @param {Engraving.Staff} destinationStaff The Staff to move system objects to.
663 : * @since 4.7
664 : */
665 : Q_INVOKABLE void moveSystemObjects(apiv1::Staff* sourceStaff, apiv1::Staff* destinationStaff);
666 :
667 : /** APIDOC
668 : * Creates and appends a new default staff to the given part.
669 : * @method
670 : * @param {Engraving.Part} destinationPart The Part to append the staff to.
671 : * @return {Engraving.Staff} The newly created Staff, or null on failure.
672 : * @since 4.7
673 : */
674 : Q_INVOKABLE apiv1::Staff* appendStaff(apiv1::Part* destinationPart);
675 :
676 : /** APIDOC
677 : * Creates a staff linked to a source staff and appends it to the given part.
678 : * The linked staff will share content with the source staff.
679 : * @method
680 : * @param {Engraving.Staff} sourceStaff The Staff to link from.
681 : * @param {Engraving.Part} destinationPart The Part to append the linked staff to.
682 : * @return {Engraving.Staff} The newly created linked Staff, or null on failure.
683 : * @since 4.7
684 : */
685 : Q_INVOKABLE apiv1::Staff* appendLinkedStaff(apiv1::Staff* sourceStaff, apiv1::Part* destinationPart);
686 :
687 : /** APIDOC
688 : * Sets the visibility of a voice on a staff.
689 : * This method only works on excerpt (linked part) scores, not on the main score.
690 : * @method
691 : * @param {Engraving.Staff} staff The Staff object.
692 : * @param {Number} voiceIndex The voice index (0 to 3).
693 : * @param {Boolean} visible Whether the voice should be visible.
694 : * @return {Boolean} True if successful, false if not an excerpt or voice cannot be disabled.
695 : * @since 4.7
696 : */
697 : Q_INVOKABLE bool setVoiceVisible(apiv1::Staff* staff, int voiceIndex, bool visible);
698 :
699 : /** APIDOC
700 : * Replaces the drumset of a part's percussion instrument.
701 : * Use Instrument.cloneDrumset() to get a modifiable copy, update it with the
702 : * available Drumset setter methods (`setName()`, `setNoteHead()`, `setLine()`,
703 : * `setVoice()`, `setStemDirection()`, `setShortcut()`), and then pass the
704 : * modified drumset to this method.
705 : * @method
706 : * @param {Engraving.Part} part The Part object.
707 : * @param {Fraction} tick The tick position (use fraction(0, 1) for the beginning).
708 : * @param {Engraving.Drumset} drumset The new Drumset to apply.
709 : * @since 4.7
710 : */
711 : Q_INVOKABLE void replaceDrumset(apiv1::Part* part, apiv1::Fraction* tick, apiv1::Drumset* drumset);
712 :
713 : /** APIDOC
714 : * Inserts a part with the instrument defined by `instrumentId` at the given index.
715 : * @method
716 : * @param {String} instrumentId ID of the instrument to be added,
717 : * as listed in {@link https://github.com/musescore/MuseScore/blob/master/share/instruments/instruments.xml|instruments.xml}
718 : * @param {Number} index The position to insert the part at (0 = first).
719 : * @since 4.7
720 : */
721 : Q_INVOKABLE void insertPart(const QString& instrumentId, int index);
722 :
723 : /** APIDOC
724 : * Replaces a part with a new instrument, keeping the same position.
725 : * This removes the old part and inserts a new one with the given instrument.
726 : * @method
727 : * @param {Engraving.Part} part The Part to replace.
728 : * @param {String} instrumentId ID of the new instrument,
729 : * as listed in {@link https://github.com/musescore/MuseScore/blob/master/share/instruments/instruments.xml|instruments.xml}
730 : * @since 4.7
731 : */
732 : Q_INVOKABLE void replacePart(apiv1::Part* part, const QString& instrumentId);
733 :
734 : /** APIDOC
735 : * Sets the score order (e.g. "orchestral", "marching-band").
736 : * Score orders define the standard ordering of instruments and bracket/barline groupings.
737 : * @method
738 : * @param {String} orderId The ID of the score order (e.g. "orchestral", "marching-band", "jazz-combo").
739 : * @since 4.7
740 : */
741 : Q_INVOKABLE void setScoreOrder(const QString& orderId);
742 :
743 : /** APIDOC
744 : * Creates and returns a cursor to be used to navigate in the score
745 : * @method
746 : * @returns {Cursor} cursor
747 : */
748 : Q_INVOKABLE apiv1::Cursor* newCursor();
749 :
750 : /** APIDOC
751 : * For MuseScore 4 and for "dock" type plugins: to be used before score
752 : * modifications to make them undoable, and to avoid corruptions or crashes.
753 : * Starts an undoable command. Must be accompanied by a corresponding `endCmd()` call.
754 : * @method
755 : * @param {String} qActionName Optional action name that appears in Undo/Redo menus, palettes, and lists.
756 : */
757 : Q_INVOKABLE void startCmd(const QString& qActionName = {});
758 :
759 : /** APIDOC
760 : * For MuseScore 4 and for "dock" type plugins: to be used after score
761 : * modifications to make them undoable, and to avoid corruptions or crashes.
762 : * Ends an undoable command.
763 : * @method
764 : * @param {Boolean} rollback If true, reverts all the changes made since the last `startCmd()` invocation.
765 : */
766 : Q_INVOKABLE void endCmd(bool rollback = false);
767 :
768 0 : apiv1::Selection* selection() { return selectionWrap(&score()->selection()); }
769 :
770 : QQmlListProperty<apiv1::Excerpt> excerpts() const;
771 :
772 : /** APIDOC
773 : * Put an item in the user's view.
774 : * @method
775 : * @param {Engraving.EngravingItem} item The item to put into view.
776 : * @param {Number} staffIdx If provided, the specific staff to put into view.
777 : * @since 4.6
778 : */
779 : Q_INVOKABLE void showElementInScore(apiv1::EngravingItem* element, int staffIdx = -1);
780 :
781 : /** APIDOC
782 : * Create PlayEvents for all notes based on ornamentation.
783 : * You need to call this if you are manipulating PlayEvent's
784 : * so that all ornamentations are populated into Note's PlayEvent lists.
785 : * @method
786 : * @deprecated PlayEvents don't have a playback effect in MuseScore 4.
787 : */
788 : Q_INVOKABLE void createPlayEvents();
789 :
790 : static const mu::engraving::InstrumentTemplate* instrTemplateFromName(const QString& name); // used by PluginAPI::newScore()
791 :
792 14 : mu::engraving::Score* score() { return toScore(e); }
793 0 : const mu::engraving::Score* score() const { return toScore(e); }
794 : private:
795 :
796 : Segment* lastSegment();
797 :
798 : mu::notation::INotationPtr notation() const;
799 : mu::notation::INotationUndoStackPtr undoStack() const;
800 : };
801 : }
|
