addNote() and addRest()

In addition to what is described in the Doxygen documentation, please note the following:

Each call to cursor.addNote() or cursor.addRest() advances the cursor, by the amount set by cursor.setDuration(), except when the cursor is already at the final beat of the last measure in the score. CAUTION: They do not return falsy value, using cursor advancement logic as loop conditional statement may leads to infinite loop error.

(Assumption: my guess is that this behaviour occurs because the plugin API is using the underlying C++ code that implements the user-interface for adding notes; and in the context of a human at the keyboard this makes perfect sense. In that case there is no longer any room left for the cursor to advance to. This would generally be true inside a plugin as well; however, if you are walking a staff in a plugin, adding notes, you'd be doing that inside a while-loop and testing for the end of the staff. In this situation failure to trap the final note's non-cursor-advancement may cause an infinite-loop condition.)