Cursor can be used by plugins to manipulate the score.
More...
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.
◆ 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
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.
|
◆ add()
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()
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()
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:
cursor.addTuplet(fraction(3, 2), fraction(1, 4));
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()
Move the cursor to the next segment.
- Returns
false
if the end of the score is reached, true
otherwise.
◆ 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()
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()
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()
◆ filter
◆ inputStateMode
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
Key signature of current staff at tick pos.
(read only)
◆ stringNumber
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