This plug-in example "locks" the page layout. It uses a browser class to parse through the pages within the specified measure region. If no measure selection was specified by the user, the full document will be processed.

For the first measure at each page, the plug-in puts a 'Start New Page' attribute for that measure.

First, the class declaration of a custom iterator handler.

class FCMyIteratorHandler : public FCIteratorHandler
{
    bool lock;
    FCMusicRegion* pRegion;
public:    
    FCMyIteratorHandler(bool value, FCMusicRegion* pTheRegion) : FCIteratorHandler()
    {
        lock = value;
        pRegion = pTheRegion;
    }
 
    virtual bool Iterate(__FCBase* pObject);
};

The implementation of FCMyIteratorHandler::Iterate() provides the core functionality for the iterator handler. This code will be run once for each page when the browser runs.

Note that much of the functionality in this method actually deals with the Automatic Update Layout setting in Finale: data can be marked as "not updated" at any time, which means that for both the page data and measures a new page update much be required to get the required data.

bool FCMyIteratorHandler::Iterate(__FCBase* object)
{
    FCPage* pPage = (FCPage*) object;    
    FCStaffSystem staffsystem;
 
    /* Update the layout if necessary: */
    if (!pPage->GetFirstSystem()) pPage->UpdateLayout();
 
    if (staffsystem.Load(pPage->GetFirstSystem())) {
        twobyte measureno = staffsystem.GetFirstMeasure();
        if (!measureno)
        {
            /* Update the layout if necessary: */
            pPage->UpdateLayout();
            if (!staffsystem.Load(pPage->GetFirstSystem())) return true;
        }
        measureno = staffsystem.GetFirstMeasure();
        if (pRegion->IsMeasureIncluded(measureno)) {
            /* Set the page break if it's in the region that should be processed: */
            FCMeasure measure;
            if (measure.Load(measureno)) {
                measure.SetPageBreak(lock);
                measure.Save();
            }
        }
    }
    return true;  // Continue with next page
}

The code to browse through the pages and use the iterator handler becomes pretty simple. The browser is set up statically, which is used to call all pages by using the custom iterator object. The ForEach() method call (highlighted below) is the row where the iterator handler is activated.

void LockPages(FCMusicRegion* pRegion, bool lock)
{
    FCBrowserPages pages;        
    FCMyIteratorHandler *pMyIteratorHandler = new FCMyIteratorHandler(lock, pRegion);    
    pages.ForEach(pMyIteratorHandler);    delete pMyIteratorHandler;
}

This plug-in will mute or turn on playback for entries in a selected region. To achieve this, very few lines of code is needed!

The class declaration of the custom iterator handler:

class FCEntryPlaybackIH : public FCIteratorHandler
{
    bool playback;
public:
    FCEntryPlaybackIH(bool shouldplayback) : FCIteratorHandler()
        { playback = shouldplayback; }
    virtual bool Iterate(__FCBase* object);
};

The implementation of the Iterate method. The method returns true to signal that the next entry whould be processed (resulting in that all entries are processed).

bool FCEntryPlaybackIH::Iterate(__FCBase* object)
{
    FCNoteEntry* pEntry = (FCNoteEntry*) object;
    if (pEntry->IsNote()) pEntry->SetPlayback(playback);
    return true;
}

The part that runs the iterator handler for the region looks like this. A browser is used for the note entries, since there's no need to collect all the entries into a collection. The playback parameter decides if the entries should be played back or be muted.

void MuteOrUnmuteNotes(FCMusicRegion* pRegion, bool playback)
{
    FCBrowserNoteEntries browser;
    FCEntryPlaybackIH myIteratorHandler(playback);
    myIteratorHandler.SetSaveAfterIterate(true);
    browser.ForEachInRegion(&myIteratorHandler, pRegion);
}

This plug-in will put double barlines and break multi-measure rests at all key signature changes. It will not put double barlines when there's a minor/major key change but with accidentals unchanged, although this behavior is easy to change.

The example shows both the use of a collection class and a iterator handler. Please note that the implementation of the iterator handler assumes that a collection is used - it has to be modified if a browser class is used.

The definition the the iterator handler looks like this:

class FCDblBarlineIteratorHandler : public FCIteratorHandler
{
     FCKeySignature* pPrevKey; /* A pointer to the previous key sig */
     FCMeasure* pPrevMeasure;  /* A pointer to the previous
                               * measure in the measure collection */
public:
    FCDblBarlineIteratorHandler() : FCIteratorHandler()
    {
        pPrevKey = NULL;
        pPrevMeasure = NULL;
    }    
    virtual bool Iterate(__FCBase* pObject);
};

The implementation of the Iterate method in the iterator handler looks like this. If you would like the plug-in to put double barlines for any kind of key change (even when there's just a minor/major mode change), change the highlighted rows below into if ((pPrevKey->GetKeyID() != pNewKey->GetKeyID()).

Note that the implementation assumes that there's a collection of measures, since the pPrevMeasure will point to the previously measure processed in the collection. Also, please note that since the previous measure will still exist in the collection, the pointer to the previous key signature will also still be available.

bool FCDblBarlineIteratorHandler::Iterate(__FCBase* pObject)
{
    FCMeasure* pMeasure = (FCMeasure*) pObject;       
    FCKeySignature *pNewKey = pMeasure->GetKeySignature();
    if (pPrevKey)
    {
        if ((pPrevKey->CalcSharps() != pNewKey->CalcSharps()) ||
                 (pPrevKey->CalcFlats() != pNewKey->CalcFlats()))        
        {
            pPrevMeasure->SetBarline(FCMeasure::BARLINE_DOUBLE);
            pPrevMeasure->SetBreakMMRest(true);
            pPrevMeasure->Save();
        }
    }    
    pPrevKey = pNewKey;
    pPrevMeasure = pMeasure;
    return true;
}

The code for using the iterator handler on a measure collection follows. It loads the measures in the supplied region, and then calls the Iterate method once for each measure.

void DoubleBarlines(FCMusicRegion* pRegion)
{
    FCMeasures measures;
    measures.LoadRegion(pRegion);
    FCDblBarlineIteratorHandler myIteratorHandler;
    measures.ForEach(&myIteratorHandler);
}

A collection class stores objects of the same kind in a collection, where each item can be identified by an index. It's very similar to an C++ array.

A browser class is a bit similar to a collection class. The difference is that while the a collection will keep all its items like an array, the browser class will not store any items in a permanent location.

The browser class parses through the Finale database, one item at a time.

A browser class are more memory efficient than a collection class, but it can get more time-consuming if the same records need processing more than once.

At some occasions browser classes are a superior choice, for example:

• When the data objects need to be processed only once

• When searching the Finale database for specific information

The Lock Page Layout Example shows the browser class in action. Here the browser approach was chosen, since each page only need to be processed once.

The most common method to use a browse class is with the ForEach method, since a browser class doesn't provide as many iteration methods as a collection class.

Iterator handlers were inspired by the code block (or closure) concept in the great Ruby script programming language. They provide a mechanism to separate functionality from data storage in "collection-type" classes. With iterator handles, you first decide in what way to parse the collection, then you "send" the processing functionality to that particular parser.

Iterator handlers are used by both collection classes and browser classes. If the implementation of the iterator handler doesn't assume that the supplied data is stored in a certain way, iterator handles can be used interchangeably by both collection classes and browser classes.

Please note that iterator handlers are not covered by the type-safe linkage in C++. It's up to the programmer to make sure that the object type passed to the iterator handler is a known type. For example, sending measure objects to an iterator handle that assumes staff objects will most likely crash.