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

Inheritance diagram for PluginAPI:

Collaboration diagram for PluginAPI:

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::Score *	newScore (const QString &name, const QString &part, int measures)

Q_INVOKABLE Ms::PluginAPI::Element *	newElement (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::Score *	readScore (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::FractionWrapper *	fraction (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::Score >	scores
	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	NoteHeadScheme
	Contains Ms::NoteHead::Scheme 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

Ms::PluginAPI::Enum	SymId
	Contains Ms::SymId enumeration values. More...

Ms::PluginAPI::Enum	HarmonyType
	Contains Ms::HarmonyType enumeration values. More...

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

elementType Element 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

name	Path to the file to be opened.
noninteractive	Can 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

Element type.

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
undoRedo - whether this onScoreStateChanged invokation results from user undo/redo action. It is usualy not recommended to modify score from plugins in this case. Available since MuseScore 3.5.

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

enclose all modifications within Score::startCmd() / Score::endCmd()
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

s	The score which should be saved.
name	Path where to save the score, with or without the filename extension (the extension is determined by `ext` parameter).
ext	Filename extension without the dot, e.g. `"mscz"` or `"pdf"`. Determines the file format to be used.

Property Documentation

◆ Align

Ms::PluginAPI::Enum Align

read

Contains Ms::Align enumeration values.

Since: MuseScore 3.3

◆ Direction

Ms::PluginAPI::Enum Direction

read

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

Ms::PluginAPI::Enum GlissandoStyle

read

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.

◆ HarmonyType

Ms::PluginAPI::Enum HarmonyType

read

Contains Ms::HarmonyType enumeration values.

Since: MuseScore 3.6

◆ 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).

◆ NoteHeadScheme

Ms::PluginAPI::Enum NoteHeadScheme

read

Contains Ms::NoteHead::Scheme enumeration values.

Since: MuseScore 3.5

◆ 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

Ms::PluginAPI::Enum NoteType

read

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

Ms::PluginAPI::Enum Placement

read

Contains Ms::Placement enumeration values.

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

◆ PlayEventType

Ms::PluginAPI::Enum PlayEventType

read

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

◆ SymId

Ms::PluginAPI::Enum SymId

read

Contains Ms::SymId enumeration values.

Since: MuseScore 3.5

◆ Tid

Ms::PluginAPI::Enum Tid

read

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:

mscore/plugin/api/qmlpluginapi.h
mscore/plugin/api/qmlpluginapi.cpp

Signals

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ newElement()

◆ readScore()

◆ removeElement()

◆ run

◆ scoreStateChanged

◆ writeScore()

Property Documentation

◆ Align

◆ Direction

◆ DirectionH

◆ division

◆ dockArea

◆ GlissandoStyle

◆ HarmonyType

◆ NoteHeadGroup

◆ NoteHeadScheme

◆ NoteHeadType

◆ NoteType

◆ NoteValueType

◆ OrnamentStyle

◆ Placement

◆ PlayEventType

◆ scores

◆ SymId

◆ Tid