MuseScore Plugins  3.5
Plugins API for MuseScore
Public Types | Public Member Functions | Properties | List of all members
Cursor Class Reference

Cursor can be used by plugins to manipulate the score. More...

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

Public Types

enum  RewindMode { SCORE_START = 0, SELECTION_START = 1, SELECTION_END = 2 }
 
enum  InputStateMode { INPUT_STATE_INDEPENDENT, INPUT_STATE_SYNC_WITH_SCORE }
 

Public Member Functions

Q_INVOKABLE void rewind (RewindMode mode)
 Rewind cursor to a certain position. More...
 
Q_INVOKABLE void rewindToTick (int tick)
 Rewind cursor to a position defined by tick. More...
 
Q_INVOKABLE bool next ()
 Move the cursor to the next segment. More...
 
Q_INVOKABLE bool nextMeasure ()
 Move the cursor to the first segment of the next measure. More...
 
Q_INVOKABLE bool prev ()
 Move the cursor to the previous segment. More...
 
Q_INVOKABLE void add (Ms::PluginAPI::Element *)
 Adds the given element to a score at this cursor's position. More...
 
Q_INVOKABLE void addNote (int pitch, bool addToChord=false)
 Adds a note to the current cursor position. More...
 
Q_INVOKABLE void addRest ()
 Adds a rest to the current cursor position. More...
 
Q_INVOKABLE void addTuplet (Ms::PluginAPI::FractionWrapper *ratio, Ms::PluginAPI::FractionWrapper *duration)
 Adds a tuplet to the current cursor position. More...
 
Q_INVOKABLE void setDuration (int z, int n)
 Set duration of the notes added by the cursor. More...
 

Properties

int track
 Current track.
 
int staffIdx
 Current staff (track / 4)
 
int voice
 Current voice (track % 4)
 
int filter
 Segment type filter, a bitmask from PluginAPI::PluginAPI::Segment values. More...
 
int tick
 MIDI tick position, read only.
 
double time
 Time at tick position, read only.
 
qreal tempo
 Tempo at current tick, read only.
 
int keySignature
 Key signature of current staff at tick pos. More...
 
Ms::PluginAPI::Score score
 Associated score.
 
Ms::PluginAPI::Element element
 Current element at track, read only.
 
Ms::PluginAPI::Segment segment
 Current segment, read only.
 
Ms::PluginAPI::Measure measure
 Current measure, read only.
 
int stringNumber
 A physical string number where this cursor currently at. More...
 
InputStateMode inputStateMode
 Behavior of input state (position, notes duration etc.) of this cursor with respect to input state of the score. More...
 

Detailed Description

Cursor can be used by plugins to manipulate the score.

Cursor object for a score can be obtained with Score::newCursor method. After creating a cursor it does not point to any location in a score. To define its initial location use rewind or rewindToTick methods. Alternatively, you can set its inputStateMode to Cursor.INPUT_STATE_SYNC_WITH_SCORE to make cursor location be synchronized with user-visible note input state.

Member Enumeration Documentation

◆ InputStateMode

Since
MuseScore 3.5
Enumerator
INPUT_STATE_INDEPENDENT 

Input state of cursor is independent of score input state (default)

INPUT_STATE_SYNC_WITH_SCORE 

Input state of cursor is synchronized with score input state.

◆ RewindMode

enum RewindMode
Enumerator
SCORE_START 

Rewind to the start of a score.

SELECTION_START 

Rewind to the start of a selection.

SELECTION_END 

Rewind to the end of a selection.

Member Function Documentation

◆ add()

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

Adds the given element to a score at this cursor's position.

◆ addNote()

void addNote ( int  pitch,
bool  addToChord = false 
)

Adds a note to the current cursor position.

The duration of the added note equals to what has been set by the previous setDuration() call.

Parameters
pitchMIDI pitch of the added note.
addToChordadd note to the current chord instead of replacing it. This parameter is available since MuseScore 3.3.4.

◆ addRest()

void addRest ( )

Adds a rest to the current cursor position.

The duration of the added rest equals to what has been set by the previous setDuration() call.

Since
MuseScore 3.5

◆ addTuplet()

void addTuplet ( Ms::PluginAPI::FractionWrapper ratio,
Ms::PluginAPI::FractionWrapper duration 
)

Adds a tuplet to the current cursor position.

This function provides a possibility to setup the tuplet's ratio to any value (similarly to Add > Tuplets > Other... dialog in MuseScore).

Examples of most typical usage:

// add a triplet of three eighth notes
cursor.addTuplet(fraction(3, 2), fraction(1, 4));
// add a quintuplet in place of the current chord/rest
var cr = cursor.element;
if (cr)
cursor.addTuplet(fraction(5, 4), cr.duration);
Parameters
ratiotuplet ratio. Numerator represents actual number of notes in this tuplet, denominator is a number of "normal" notes which correspond to the same total duration. For example, a triplet has a ratio of 3/2 as it has 3 notes fitting to the duration which would normally be occupied by 2 notes of the same nominal length.
durationtotal duration of the tuplet. To create a tuplet with duration matching to duration of existing chord or rest, use its duration value as a parameter.
Since
MuseScore 3.5
See also
DurationElement::tuplet

◆ next()

bool next ( )

Move the cursor to the next segment.

Returns
false if the end of the score is reached, true otherwise.

◆ nextMeasure()

bool nextMeasure ( )

Move the cursor to the first segment of the next measure.

Returns
false if the end of the score is reached, true otherwise.

◆ prev()

bool prev ( )

Move the cursor to the previous segment.

Returns
false if the beginning of the score is reached, true otherwise.
Since
MuseScore 3.3.4

◆ rewind()

void rewind ( RewindMode  mode)

Rewind cursor to a certain position.

Parameters
modeDetermines the position where to move this cursor. See Cursor::RewindMode to see the list of available rewind modes.
Note
In MuseScore 2.X, this function took an integer value (0, 1 or 2) as its parameter. For compatibility reasons, the old values are still working, but it is recommended to use RewindMode enumerators instead.

◆ rewindToTick()

void rewindToTick ( int  tick)

Rewind cursor to a position defined by tick.

Parameters
tickDetermines the position where to move this cursor.
See also
Segment.tick
Since
MuseScore 3.5

◆ setDuration()

void setDuration ( int  z,
int  n 
)

Set duration of the notes added by the cursor.

Parameters
znumerator
ndenominator. If n == 0, sets duration to a quarter.
See also
addNote()

Property Documentation

◆ filter

int filter
readwrite

Segment type filter, a bitmask from PluginAPI::PluginAPI::Segment values.

Determines which segments this cursor will move to on next() and nextMeasure() operations. The default value is Ms::SegmentType::ChordRest so only segments containing chords and rests are handled by default.

◆ inputStateMode

InputStateMode inputStateMode
readwrite

Behavior of input state (position, notes duration etc.) of this cursor with respect to input state of the score.

By default any changes in score and in this Cursor are not synchronized.

Since
MuseScore 3.5

◆ keySignature

int keySignature
read

Key signature of current staff at tick pos.

(read only)

◆ stringNumber

int stringNumber
readwrite

A physical string number where this cursor currently at.

This is useful in conjunction with InputStateMode.INPUT_STATE_SYNC_WITH_SCORE cursor mode.

Since
MuseScore 3.5

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