Extensions.md

Extension API

With extensions to Sibmei, text objects, symbols and lines can be exported in a customized way. This allows addressing custom symbols and text styles and project specific needs.

Extensions are regular Sibelius plugins written in ManuScript. When running Sibmei, it scans for extension plugins. Users can choose which extensions to activate when running Sibmei. Multiple extensions can be activated simultaneously.

Example

{
  //"The `SibmeiExtensionAPIVersion` field must be present so Sibmei can"
  //"recognize compatible extensions"
  SibmeiExtensionAPIVersion "1.0.0"

  Initialize "() {
    // The extension choice dialog will list this extension as
    // 'Example extension' (the first argument to to AddToPluginsMenu()).
    // Second argument can be `null` because an extension plugin does not need a
    // `Run()` method.
    AddToPluginsMenu('Example extension', null);
  }"

  //"InitSibmeiExtension() is the entry point for Sibmei and must be present"
  //"for Sibmei to recognize an extension plugin."
  InitSibmeiExtension "(api) {
    // Declare which text styles this extension handles
    api.RegisterTextHandlers(CreateDictionary(
      // Text objects can be matched either by their StyleId or StyleAsText
      // property. Here, we match by StyleAsText.
      'StyleAsText', CreateDictionary(
         // We want the HandleMyText() method to handle Text objects matching
         // textObj.StyleAsText = 'My text'
        'My text', 'HandleMyText'
      )
    ), Self);
  }"

  HandleMyText "(api, textObj) {
    // Create and return an MEI element that Sibmei will append as a child to
    // the measure element.
    textElement = api.GenerateControlEvent(textObj, api.libmei.AnchoredText());
    api.AddFormattedText(textElement, textObj);
    return textElement;
  }"
}

See another example for code handling symbols.

Required data and methods

SibmeiExtensionAPIVersion

A semantic version string specifying for which version of the Sibmei extension API the extension was written. The current API version of Sibmei can be found in GLOBALS.mss.

The API is guaranteed to remain backwards compatible with newer releases that retain the same major version number for ExtensionAPIVersion. With minor version numbers, new functionality is added while existing functionality remains backwards compatible.

InitSibmeiExtension()

Sibmei calls this method and passes an API Dictionary as argument (see below). Register your symbol and text handlers in this function using RegisterSymbolHandlers() and RegisterTextHandlers() (see below).

API Dictionary

Interaction with Sibmei

Extensions must only interact with Sibmei through the API dictionary that is passed to InitSibmeiExtension() and Handler methods because Sibmei's core methods may change at any point. If an extension requires access to functionality that is not exposed by the API dictionary, create an issue or a pull request on GitHub.

API data and methods

The API dictionary exposes the following object:

• libmei: A reference to libmei that can be used to construct and manipulate MEI elements. This dictionary must not be modified.

Registering Text, Symbol and Line styles

The API dictionary exposes the following methods for registering Handlers that must only be used inside the InitSibmeiExtension() method:

• RegisterSymbolHandlers()

• RegisterTextHandlers()

• RegisterLineHandlers()

The following methods can be used by Handler methods:

• AddFormattedText()
• GenerateControlEvent()
• GenerateModifier()
• MeiFactory()