Q: When you load something into the rosegardengui from an XML file,
what sort of structure is stored?  (Which header files define this?)

A: Elements are stored in XMLStorableEvent objects
(xmlstorableevent.h). This class allows building an event from an XML
element and dumping that event into an XML element
(XMLStorableEvent::toXMLString()).

These events are stored into a Track (defined in core/Track.h). Right
now this structure is a multiset<>, rather than a list or a
vector. The reason for this is simply that a multiset<> is ordered by
definition (in our case, ordered by time stamp), so we don't have to
worry about keeping our elements in the right order.


Q: Is the structure of Qt canvas objects physically the same data
structure as the main storage, or are the stored objects converted
into canvas objects for display?  (Which source files do this
conversion, if so, and when does it happen, and is it done en masse or
in small parts on demand?)

A: No, the canvas elements are seperate from the actual events. The
class doing the conversion (transforming an EventList into a
NotationElementList) is the ViewElementsManager, defined in
viewelementsmanager.h. ViewElementsManager::getNotationElementList()
is the method doing the conversion. It is called once after the
loading. Newly inserted notes are processed in NotationView's tool
classes and in TrackNotationHelper::insertNote
(core/TrackNotationHelper.h) and related methods.

The ViewElement class, which associates an Event to a view element is
defined in core/ViewElement.h. This class should be derived for each
kind of "visual" element: a canvas item for the notation layout, a
whatever-that-will-be in the sequencer (I'm not quite sure there will
be such a thing though).

Note that a NotationElement is not a QCanvasItem, it just wraps
one. It also has its own x,y coordinates (I think this is because the
canvas item doesn't always necessarily exist), but they are maintained
as to be identical to those of the canvas item.


Q: When you click on the canvas to insert an item, what series of
events takes place?  (Which object gets the initial event, what
structure does it examine to locate the position where the click took
place, what is then modified to insert the new object, and how does
notice of the new insertion get propagated back to the display?)

A: [This answer is out of date] The object which gets the initial
event is the NotationCanvasView (in notationcanvasview.h). This class
derives from QCanvasView, which is a QCanvas in a ScrollView window.

The NotationCanvasView checks if the mouse press was on a staff line
(see NotationCanvasView::contentsMousePressEvent()). Staff lines are
actually canvas items, which know which pitch they correspond to
(remember that there are also white staff lines between each black
one). If so, it calls insertNote() which merely emits the noteInserted
signal.

This signal is connected to NotationView::insertNote(). The
NotationView object is the toplevel window holding the
NotationCanvasView. This is where the "hairy stuff" happens.

1. the Event corresponding to the inserted note is created
2. the corresponding NotationElement is created
3. the closest note to that element is found

   - if it's a rest, it is replaced by the note if it's of the same
     duration, or by the note + a rest so that both are of the same
     duration as the replaced rest.

   - if it's a note, the new note is added over it, as counterpoint.

   - if it's at the end of the staff, nothing happens (which leaks the
     Event btw :-).

4. The new NotationElement is positioned vertically (vertical layout
   is called)

5. The whole staff is getting laid (sorry, couldn't resist). That is,
   horizontal layout is called on the whole staff. We can be more
   subtle that this. There currently is an attempt at that (see the
   redoLayoutStart iterator) but it's not working for the
   horiz. layout because this one needs to compute note times from the
   beginning to set where bar lines are.

6. Each NotationElement is "shown", that is,
   NotationView::showElements() is called. This creates the
   appropriate pixmap for each NotationElement. Right now this means
   all canvas items are re-created for each layout, which sucks.

