Score API

Two groups of methods:

  1. For creation and modification
  2. For traversing and analyzing

Representation of a score

A score is treated as a hierarchy: each score contains 0 or more staves and each staff contains `staff objects' (staffobjs). Clefs, text and chords are all different types of staff objects.

Traversing methods

VStaff methods

wxInt32 GetNumMeasures();

lmStaffObjIterator* CreateIterator(ETraversingOrder nOrder);

int GetNumStaves();

lmStaff* GetFirstStaff();

lmStaff* GetNextStaff();

lmStaff* GetLastStaff();

lmStaff* GetStaff(wxInt32 nStaff);

Staff Objects traversing methods

Once an iterator has been created, the iterator admits the following methods:

bool EndOfList();

lmStaffObj* GetCurrent();

void AdvanceToMeasure(int nBar);

void MoveFirst();

void MoveNext();

void MovePrev();

void MoveLast();

void BackToItemOfType(EScoreObjType nType);

void GoToItem(lmStaffObj* pSO);

Working with staff objects iterators

Usually it is necessary to do some operation to every staff in a score, or every bar in a staff, or every note in a score.

Three posibilities:

  1. traverse the staff objects in chronological order (eTR_ByTime), or
  2. do it in the order they are internally stored (eTR_AsStored), or
  3. do it in the fastest method (eTR_OptimizeAccess).

The procedure is as follows:

  1. Create an iterator of the most appropiate type. After creation current element pointer points to first staff object (according to selected ordering)
  2. It can be tested test if current element points to a valid Staff object by using method EndOfList()
  3. TO reposition curren element pointer use methods AdvanceToMeasure(), MoveFirst(), MoveNext(), MovePrev(), MoveLast(), BackToItemOfType() and GoToItem().
  4. Finally, when the iterator is no longer needed, destroy it. This is important; otherwise you will get memory leaks!

Example:

    lmStaffObj* pSO;
    lmStaffObjIterator* pIter = pVStaff->CreateIterator(eTR_ByTime);
    while(!pIter->EndOfList()) {
        pSO = pIter->GetCurrent();
        // ...do something with pSO
        pIter->MoveNext();
    }
    delete pIter;