Events store pitch values in simple integers. These are fixed-frequency pitches in the MIDI pitch scale, independent of clef and key. Adding 12 to a pitch increments it by one octave; pitch 60 is the treble-clef middle C. (Previous rewrites have considered using double the MIDI pitch so as to allow quarter-tones; this time let's go for the simpler option as if we ever want quarter-tones we can always code them using special Event properties.)
For notation purposes we need a display pitch, which is a composite of height on the staff plus accidental. The correspondence between display pitch and raw pitch depends on the clef and key. For height on the staff, we use the RG2.1 convention of 0 = bottom line, 1 = gap between bottom two lines and so on up to 8 = top line. Negative heights are below the staff (i.e. on leger lines), heights over 8 are above. Display pitch is therefore independent of clef, so height 0 is always the bottom line in any clef.
If we ever see pitch as a plain integer, we assume it's a raw internal pitch rather than a display pitch. A plain integer used for display pitch would probably be referred to as a “height” rather than a pitch, as it would be lacking the extra information (accidental, clef, key) required to interpret it as a true pitch.
This part of the original documentation is completely obsolete.
All I've ever needed to know is that a quarter note is 960 units, and everything else multiplies or divides from there.
Tempo specifications are usually informally described in beats per minute (bpm). However, as far as sequencers are concerned tempo is generally measured in crotchets (quarter-notes) per minute, regardless of the actual value of a beat in the current time-signature. And the MIDI file format inverts this, recording tempo in pulses per quarter-note (ppq).
For Rosegarden we choose to encode tempo in crotchets per minute, but because we may want to have non-integral values and the Event mechanism doesn't support floating-point properties, we actually store crotchets per hour and convert to and from floating-point per-minute values in the API. We will also continue to use the name “bpm” even though our “beat” is not always strictly a beat (it is always a crotchet).
The range used by MIDI to represent velocity (initial relative volume of a note) is 0-127, with maximum at 127 and silence at 0. We use the same range to store velocity values.
(But note that some components such as the VU meters refer to levels in a floating-point 0.0 → 1.0 range.)
Bar numbers are counted from 1 on the GUI (i.e. the first non-count-in bar is by default bar 1), but are counted from 0 internally (because we're sad geeks). That means we have to add 1 every time we display a bar number, and subtract 1 from any the user supplies.
Absolute times and bar numbers can both legitimately be negative, so we need to use signed types, to avoid treating values like -1 as special no-value cases, and to avoid making assumptions such as that we can enumerate all bars by counting from zero.
The “bar” referred to here is currently an internal unit as well as an outward representation of barlines on a staff in a notation view, but this system is not adequate to address the needs of music notation. Eventually we need some other way to represent barlines on a staff that's independent of our internal “bar” unit.