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

Inheritance diagram for Cursor:

Collaboration diagram for Cursor:

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

enum 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

pitch	MIDI pitch of the added note.
addToChord	add 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

ratio	tuplet 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.
duration	total 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

mode	Determines 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

tick	Determines 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

z	numerator
n	denominator. 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:

mscore/plugin/api/cursor.h
mscore/plugin/api/cursor.cpp

Public Types

Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

◆ InputStateMode

◆ RewindMode

Member Function Documentation

◆ add()

◆ addNote()

◆ addRest()

◆ addTuplet()

◆ next()

◆ nextMeasure()

◆ prev()

◆ rewind()

◆ rewindToTick()

◆ setDuration()

Property Documentation

◆ filter

◆ inputStateMode

◆ keySignature

◆ stringNumber