MuseScore Plugins  3.4
Plugins API for MuseScore
Signals | Public Member Functions | Properties | List of all members
PluginAPI Class Reference

Main class of the plugins framework. Named as MuseScore in QML. More...

Inheritance diagram for PluginAPI:
Inheritance graph
[legend]
Collaboration diagram for PluginAPI:
Collaboration graph
[legend]

Signals

void run ()
 Indicates that the plugin was launched. More...
 
void scoreStateChanged (const QMap< QString, QVariant > &state)
 Notifies plugin about changes in score state. More...
 

Public Member Functions

Q_INVOKABLE Ms::PluginAPI::ScorenewScore (const QString &name, const QString &part, int measures)
 
Q_INVOKABLE Ms::PluginAPI::ElementnewElement (int)
 Creates a new element with the given type. More...
 
Q_INVOKABLE void removeElement (Ms::PluginAPI::Element *wrapped)
 Disposes of an Element and its children. More...
 
Q_INVOKABLE void cmd (const QString &)
 
Q_INVOKABLE bool writeScore (Ms::PluginAPI::Score *, const QString &name, const QString &ext)
 Writes a score to a file. More...
 
Q_INVOKABLE Ms::PluginAPI::ScorereadScore (const QString &name, bool noninteractive=false)
 Reads the score from a file and opens it in a new tab. More...
 
Q_INVOKABLE void closeScore (Ms::PluginAPI::Score *)
 
Q_INVOKABLE void log (const QString &)
 
Q_INVOKABLE void logn (const QString &)
 
Q_INVOKABLE void log2 (const QString &, const QString &)
 
Q_INVOKABLE void openLog (const QString &)
 
Q_INVOKABLE void closeLog ()
 
Q_INVOKABLE Ms::PluginAPI::FractionWrapperfraction (int numerator, int denominator) const
 Creates a new fraction with the given numerator and denominator.
 

Properties

QString menuPath
 Path where the plugin is placed in menu.
 
QString filePath
 Source file path, without the file name (read only)
 
QString version
 Version of this plugin.
 
QString description
 Human-readable plugin description, displayed in Plugin Manager.
 
QString pluginType
 Type may be dialog, dock, or not defined.
 
QString dockArea
 Where to dock on main screen. More...
 
bool requiresScore
 Whether the plugin requires an existing score to run, default is true
 
int division
 Number of MIDI ticks for 1/4 note (read only) More...
 
int mscoreVersion
 Complete version number of MuseScore in the form: MMmmuu (read only)
 
int mscoreMajorVersion
 1st part of the MuseScore version (read only)
 
int mscoreMinorVersion
 2nd part of the MuseScore version (read only)
 
int mscoreUpdateVersion
 3rd part of the MuseScore version (read only)
 
qreal mscoreDPI
 (read-only)
 
Ms::PluginAPI::Score curScore
 Current score, if any (read only)
 
QQmlListProperty< Ms::PluginAPI::Scorescores
 List of currently open scores (read only). More...
 
Ms::PluginAPI::Enum Element
 Contains Ms::ElementType enumeration values.
 
Ms::PluginAPI::Enum Accidental
 Contains Ms::AccidentalType enumeration values.
 
Ms::PluginAPI::Enum Beam
 Contains Ms::Beam::Mode enumeration values.
 
Ms::PluginAPI::Enum Placement
 Contains Ms::Placement enumeration values. More...
 
Ms::PluginAPI::Enum Glissando
 Contains Ms::GlissandoType enumeration values.
 
Ms::PluginAPI::Enum LayoutBreak
 Contains Ms::LayoutBreak::Type enumeration values.
 
Ms::PluginAPI::Enum Lyrics
 Contains Ms::Lyrics::Syllabic enumeration values.
 
Ms::PluginAPI::Enum Direction
 Contains Ms::Direction enumeration values. More...
 
Ms::PluginAPI::Enum DirectionH
 Contains Ms::MScore::DirectionH enumeration values. More...
 
Ms::PluginAPI::Enum OrnamentStyle
 Contains Ms::MScore::OrnamentStyle enumeration values. More...
 
Ms::PluginAPI::Enum GlissandoStyle
 Contains Ms::GlissandoStyle enumeration values. More...
 
Ms::PluginAPI::Enum Tid
 Contains Ms::Tid enumeration values. More...
 
Ms::PluginAPI::Enum Align
 Contains Ms::Align enumeration values. More...
 
Ms::PluginAPI::Enum NoteType
 Contains Ms::NoteType enumeration values. More...
 
Ms::PluginAPI::Enum PlayEventType
 Contains Ms::PlayEventType enumeration values. More...
 
Ms::PluginAPI::Enum NoteHeadType
 Contains Ms::NoteHead::Type enumeration values. More...
 
Ms::PluginAPI::Enum NoteHeadGroup
 Contains Ms::NoteHead::Group enumeration values. More...
 
Ms::PluginAPI::Enum NoteValueType
 Contains Ms::Note::ValueType enumeration values. More...
 
Ms::PluginAPI::Enum Segment
 Contains Ms::SegmentType enumeration values.
 
Ms::PluginAPI::Enum Spanner
 

Detailed Description

Main class of the plugins framework. Named as MuseScore in QML.

This class is exposed to QML plugins framework under MuseScore name and is the root component of each MuseScore plugin.

Member Function Documentation

◆ newElement()

Element * newElement ( int  elementType)

Creates a new element with the given type.

The element can be then added to a score via Cursor::add.

Parameters
elementTypeElement type, should be the value from PluginAPI::PluginAPI::Element enumeration.

◆ readScore()

Score * readScore ( const QString &  name,
bool  noninteractive = false 
)

Reads the score from a file and opens it in a new tab.

Parameters
namePath to the file to be opened.
noninteractiveCan be used to avoid a "save changes" dialog on closing a score that is either imported or was created with an older version of MuseScore.

◆ removeElement()

void removeElement ( Ms::PluginAPI::Element wrapped)

Disposes of an Element and its children.

Parameters
Elementtype.
Since
MuseScore 3.3

◆ run

void run ( )
signal

Indicates that the plugin was launched.

Implement onRun() function in your plugin to handle this signal.

◆ scoreStateChanged

void scoreStateChanged ( const QMap< QString, QVariant > &  state)
signal

Notifies plugin about changes in score state.

Called after each user (or plugin) action which may have changed a score. Implement onScoreStateChanged() function in your plugin to handle this signal.

state variable is available within the handler with following fields:

  • selectionChanged
  • excerptsChanged
  • instrumentsChanged
  • startLayoutTick
  • endLayoutTick

If a plugin modifies score in this handler, then it should:

  1. enclose all modifications within Score::startCmd() / Score::endCmd()
  2. take care of preventing an infinite recursion, as plugin-originated changes will trigger this signal again after calling Score::endCmd()

Example:

import QtQuick 2.0
import MuseScore 3.0
MuseScore {
menuPath: "Plugins.selectionChangeExample"
pluginType: "dock"
dockArea: "left"
implicitHeight: 75 // necessary for dock widget to appear with nonzero height
implicitWidth: 150
Text {
// A label which will display pitch of the currently selected note
id: pitchLabel
anchors.fill: parent
}
onScoreStateChanged: {
if (state.selectionChanged) {
var el = curScore ? curScore.selection.elements[0] : null;
if (el && el.type == Element.NOTE)
pitchLabel.text = el.pitch;
else
pitchLabel.text = "no note selected";
}
}
}
Warning
This functionality is considered experimental. This API may change in future versions of MuseScore.
Since
MuseScore 3.3

◆ writeScore()

bool writeScore ( Ms::PluginAPI::Score s,
const QString &  name,
const QString &  ext 
)

Writes a score to a file.

Parameters
sThe score which should be saved.
namePath where to save the score, with or without the filename extension (the extension is determined by ext parameter).
extFilename extension without the dot, e.g. "mscz" or "pdf". Determines the file format to be used.

Property Documentation

◆ Align

Contains Ms::Align enumeration values.

Since
MuseScore 3.3

◆ Direction

Contains Ms::Direction enumeration values.

Note
In MuseScore 2.X this enumeration was available as MScore.UP, MScore.DOWN, MScore.AUTO.

◆ DirectionH

Ms::PluginAPI::Enum DirectionH
read

Contains Ms::MScore::DirectionH enumeration values.

Note
In MuseScore 2.X this enumeration was available as MScore.LEFT, MScore.RIGHT, MScore.AUTO.

◆ division

int division
read

Number of MIDI ticks for 1/4 note (read only)

See also
Tick Length values

◆ dockArea

QString dockArea
readwrite

Where to dock on main screen.

Possible values: left, top, bottom, right

◆ GlissandoStyle

Contains Ms::GlissandoStyle enumeration values.

Note
In MuseScore 2.X this enumeration was available as MScore.CHROMATIC, MScore.WHITE_KEYS, MScore.BLACK_KEYS, MScore.DIATONIC.

◆ NoteHeadGroup

Ms::PluginAPI::Enum NoteHeadGroup
read

Contains Ms::NoteHead::Group enumeration values.

Note
In MuseScore 2.X this enumeration was available in NoteHead class (e.g. NoteHead.HEAD_TRIANGLE).

◆ NoteHeadType

Ms::PluginAPI::Enum NoteHeadType
read

Contains Ms::NoteHead::Type enumeration values.

Note
In MuseScore 2.X this enumeration was available in NoteHead class (e.g. NoteHead.HEAD_QUARTER).

◆ NoteType

Contains Ms::NoteType enumeration values.

Since
MuseScore 3.2.1

◆ NoteValueType

Ms::PluginAPI::Enum NoteValueType
read

Contains Ms::Note::ValueType enumeration values.

Note
In MuseScore 2.X this enumeration was available as Note.OFFSET_VAL, Note.USER_VAL

◆ OrnamentStyle

Ms::PluginAPI::Enum OrnamentStyle
read

Contains Ms::MScore::OrnamentStyle enumeration values.

Note
In MuseScore 2.X this enumeration was available as MScore.DEFAULT, MScore.BAROQUE.

◆ Placement

Contains Ms::Placement enumeration values.

Note
In MuseScore 2.X this enumeration was available as Element.ABOVE and Element.BELOW.

◆ PlayEventType

Contains Ms::PlayEventType enumeration values.

Since
MuseScore 3.3

◆ scores

QQmlListProperty< Score > scores
read

List of currently open scores (read only).


Since
MuseScore 3.2

◆ Tid

Contains Ms::Tid enumeration values.

Note
In MuseScore 2.X this enumeration was available as TextStyleType (TextStyleType.TITLE etc.)

The documentation for this class was generated from the following files: