Cursor Object

Updated 4 years ago

This documentation applies to plugins for 1.x only!

Documentation for 2.x+ is built into the Plugin Creator of Musescore.

( ⇒ In Musescore press Ctrl+Shift+P, then F1 to bring it up. )

Click here for Documentation for 3.x

Cursors allows navigation in an open score and allows access to its elements. A cursor exists purely within the plugin which creates it and has no relationship to the 'blue cursor' visible in the MuseScore GUI. A cursor can access only the Score Object for which it is initially created.

A new Cursor can be created with:
  cursor = new Cursor(score);
or
  cursor = new Cursor(score, expandRepeat);
where:

  • score is an existing Score Object which the cursor will be able to browse;
  • expandRepeat is a bool value: if true the cursor will obey score repetitions and voltas.

After the cursor is created, it should be rewind()-ed.

See also:

Chord Object , Measure Object , Rest Object , Score Object , Text Object

Properties

Name Type Description
pageNumber integer contains the score page the cursor currently is in (read-only).
staff integer contains the staff the cursor is browsing; staves are numbered from top to bottom, starting with 0; the number of staves of a score can be obtained with score.staves. Can be set to access a different staff.
voice integer contains the voice (within the current staff) the cursor is currently browsing; voices are numbered from top to bottom, from 0 to 3. Can be set to access a different voice of the current staff.

Methods

add(Chord chord)

Adds the Chord chord at the current cursor position (replacing what is currently there).
Moves the cursor to the next Chord/Rest of the current voice of the current staff.

add(Rest rest)

Adds the Rest rest at the current cursor position (replacing what is currently there).
Moves the cursor to the next Chord/Rest of the current voice of the current staff.

Chord chord()

Returns the Chord at the current cursor position, if any. Care should be taken to ensure the cursor is currently pointing at a chord, for instance by using the method isChord().

bool eos()

Returns true if the cursor is currently at end of the current voice/staff of the score.

goToSelectionStart()

Positions the cursor at the chord or rest at the beginning of the selection, voice will be 0 and staff will be set to the first staff in the selection. If you want something different, you need to set them after the goTo. If no selection exists in that score, the cursor will be positioned at the end of score, i.e. cursor.eos() would return true.
Note: a single 'blue' note or rest is not considered a selection; only extended selections ('blue rectangles') are taken into account.

goToSelectionEnd()

Positions the cursor immediately after the last chord or rest at the end of selection, voice will be 0 and staff will be set to the next staff after the selection (even if that doesn't exist). If you want something different, you need to set them after the goTo. If no selection exists in that score, the cursor will be positioned at the end of score, i.e. cursor.eos() would return true.
Note: a single 'blue' note or rest is not considered a selection; only extended selections ('blue rectangles') are taken into account.

bool isChord()

Returns true if the cursor points to a Chord.

isRest()

Returns true if the cursor points to a Rest.

Measure measure()

Returns the Measure at the current position.

next()

Moves the cursor to the next Chord/Rest of the current voice of the current staff.

nextMeasure()

Moves the cursor to the first Chord/Rest of the next Measure

QPointF pos()

Returns the x,y position (in pixels) of current element in the page.

putStaffText(Text text)

Adds the Text text as staff text at the cursor position. text shall be created previously.

Rest rest()

Returns the Rest at the current cursor position, if any. Care should be taken to ensure the cursor is currently pointing at a rest, for instance by using the method isRest().

rewind()

Positions the cursor at the beginning of the set staff / voice. After setting the staff and/or voice properties, the actual cursor position is undetermined until this method is called.

integer tick()

Returns the tick of the current position (in internal units, see Tick Length values ).

double time()

Returns the time of the current position in milliseconds.