Skip to content

Commit

Permalink
Remove double spaces in documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
th-we committed Feb 19, 2024
1 parent 8204335 commit 63a2d92
Show file tree
Hide file tree
Showing 2 changed files with 20 additions and 20 deletions.
36 changes: 18 additions & 18 deletions ExportHandlers.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,24 @@
# Handling of Text, Lines and Symbols

Text and Lines have in common that there are a multitude of different styles, and users can add their own styles. The style of a text or line object can be determined by looking at their `StyleId` and/or `StyleAsText` properties. Each style should be exported in a different fashion.
Text and Lines have in common that there are a multitude of different styles, and users can add their own styles. The style of a text or line object can be determined by looking at their `StyleId` and/or `StyleAsText` properties. Each style should be exported in a different fashion.

Symbols are similar, but instead of `StyleId` and `StyleAsText`, the properties to look at are `Index` and `Name`.

> [!NOTE]
>
> All the following code examples use an `api` prefix. This prefix is only needed when creating handlers via extension plugin. For Sibmei internal code, this prefix must be omitted.
> All the following code examples use an `api` prefix. This prefix is only needed when creating handlers via extension plugin. For Sibmei internal code, this prefix must be omitted.
## Handlers

To handle the multitude of styles and symbols, we have a mechanism to associate Handlers with the different styles and symbols. For user-defined styles and symbols, extension plugins can register additional Handlers.
To handle the multitude of styles and symbols, we have a mechanism to associate Handlers with the different styles and symbols. For user-defined styles and symbols, extension plugins can register additional Handlers.

Handlers are tiny objects with a method `HandleObject()`. The line, text or symbol object is passed to this method and the method has to generate and return an MEI element. It is also responsible for inserting them in the score. This is done by calling `GenerateControlEvent()` for control events (which adds them to `<measure>`) and `GenerateModifier()` for modifiers (which adds them to `<note>`, `<rest>` or `<chord>`).
Handlers are tiny objects with a method `HandleObject()`. The line, text or symbol object is passed to this method and the method has to generate and return an MEI element. It is also responsible for inserting them in the score. This is done by calling `GenerateControlEvent()` for control events (which adds them to `<measure>`) and `GenerateModifier()` for modifiers (which adds them to `<note>`, `<rest>` or `<chord>`).

> [!NOTE]
>
> ### Internals: Associating BarObjects with their Handlers
>
> A mapping Dictionary is used to find the Handler that is used to convert an object to MEI. There are three such mapping Dictionaries: `LineHandlers`, `TextHandlers` and `SymbolHandlers`. These dictionaries look like illustrated by the following pseudo-code:
> A mapping Dictionary is used to find the Handler that is used to convert an object to MEI. There are three such mapping Dictionaries: `LineHandlers`, `TextHandlers` and `SymbolHandlers`. These dictionaries look like illustrated by the following pseudo-code:
>
> ```js
> {
Expand All @@ -45,12 +45,12 @@ Handlers are tiny objects with a method `HandleObject()`. The line, text or symb
>
> For the `SymbolHandlers` Dictionary, the keys `Index` and `Name` are used instead of `StyleId` and `StyleAsText`.
>
> When Sibmei finds a a line or text object, it calls `HandleStyle()` (and if it finds a symbol, it uses `HandleSymbol()`), and those methods retrieve the Handler defined from the respective Handler mapping Dictionary (if any) and execute it.
> When Sibmei finds a a line or text object, it calls `HandleStyle()` (and if it finds a symbol, it uses `HandleSymbol()`), and those methods retrieve the Handler defined from the respective Handler mapping Dictionary (if any) and execute it.
>
## Creating and registering Handlers
For creating entries in the Handler mapping Dictionaries, the `RegisterSymbolHandlers()`, `RegisterLineHandlers()` and `RegisterTextHandlers()` methods are used. These functions also create the Handler objects and their `HandleObject()` methods.
For creating entries in the Handler mapping Dictionaries, the `RegisterSymbolHandlers()`, `RegisterLineHandlers()` and `RegisterTextHandlers()` methods are used. These functions also create the Handler objects and their `HandleObject()` methods.
There are two ways of registering a Handler:
Expand All @@ -70,7 +70,7 @@ api.RegisterTextHandlers('StyleId', CreateDictionary(
), Self);
```
Templates declaratively describe an MEI element by means of ManuScript data structures for example:
Templates declaratively describe an MEI element by means of ManuScript data structures for example:

```js
CreateSparseArray(
Expand Down Expand Up @@ -108,7 +108,7 @@ Only the tag name is required, all other entries are optional.

#### Control event vs. modifier

By default, the built-in template Handler adds the created element to `<measure>` as a control event. If it should instead be added to `<note>`, `<rest>` or `<chord>` as modifier, the `AsModifier` function must be used:
By default, the built-in template Handler adds the created element to `<measure>` as a control event. If it should instead be added to `<note>`, `<rest>` or `<chord>` as modifier, the `AsModifier` function must be used:

```js
api.RegisterSymbolHandlers('Index', CreateDictionary(
Expand Down Expand Up @@ -143,11 +143,11 @@ Output for a text object where the `Text` property is 'Joseph Haydn':
<persName><composer>Joseph Haydn</composer></persName>
```

Where `api.FormattedText` is used, any formatting like bold or italic will be converted to the respective MEI markup. For `api.UnformattedText`, any such formatting is stripped.
Where `api.FormattedText` is used, any formatting like bold or italic will be converted to the respective MEI markup. For `api.UnformattedText`, any such formatting is stripped.

##### Line `@endid`

When exporting Sibelius line objects (lines, hairpins, highlights etc.), the MEI object can be given an `endid` attribute that will be written automatically. In the template, the value of the attribute should be set to one of the placeholders described below.
When exporting Sibelius line objects (lines, hairpins, highlights etc.), the MEI object can be given an `endid` attribute that will be written automatically. In the template, the value of the attribute should be set to one of the placeholders described below.

Example:

Expand All @@ -165,12 +165,12 @@ The placeholder will be replaced by an ID reference when writing the XML. Which

* `'PreciseMatch'`: `@endid` will only be written if there is a NoteRest precisely at the `EndPosition` in the same voice as the line.
* `'Next'`: If there is no NoteRest at the `EndPosition`, will write an `@endid` pointing to the closest following NoteRest, if there is one in the same voice as the line.
* `'Previous'`: If there is no NoteRest at the `EndPosition`, will write an `@endid` pointing to the closest preceding NoteRest, if there is one in the same voice as the line.
* `'Previous'`: If there is no NoteRest at the `EndPosition`, will write an `@endid` pointing to the closest preceding NoteRest, if there is one in the same voice as the line.
* `'Closest'`: Writes an `@endid` that points to the closest NoteRest at the `EndPosition` in the same voice as the line.

### Registering a Handler method

Where templates do not suffice, a dedicated Handler method can be written. Here is an example from an extension, where a simple template would not be able to output different things depending on the colour of the symbol:
Where templates do not suffice, a dedicated Handler method can be written. Here is an example from an extension, where a simple template would not be able to output different things depending on the colour of the symbol:

```js
function HandleMySymbol (api, obj) {
Expand All @@ -183,9 +183,9 @@ function HandleMySymbol (api, obj) {
} //$end
```

A Handler method receives the Handler object as first argument and the symbol, text or line object as second argument. It has to call `api.GenerateControlEvent()` or `api.GenerateModifier()`, otherwise the created MEI element will note be attached to the score.
A Handler method receives the Handler object as first argument and the symbol, text or line object as second argument. It has to call `api.GenerateControlEvent()` or `api.GenerateModifier()`, otherwise the created MEI element will note be attached to the score.

In the above example, the MEI element is initially also generated from a template (that is defined as global variable `MySymbolTable`) by calling `api.MeiFactory()` directly. The very same MEI element can also be created by means of libmei:
In the above example, the MEI element is initially also generated from a template (that is defined as global variable `MySymbolTable`) by calling `api.MeiFactory()` directly. The very same MEI element can also be created by means of libmei:

```js
function HandleMySymbol (api, obj) {
Expand Down Expand Up @@ -228,21 +228,21 @@ element = api.GenerateControlEvent(bobj, api.MeiFactory(template, bobj));

#### `GenerateModifier()`

Works in the same way as `GenerateControlEvent()`, but attaches the element to `<note>`, `<chord>` or `<rest>` (depending on what's found at the position in the object's voice). Unlike `GenerateControlEvent()`, it does not add any attributes automatically.
Works in the same way as `GenerateControlEvent()`, but attaches the element to `<note>`, `<chord>` or `<rest>` (depending on what's found at the position in the object's voice). Unlike `GenerateControlEvent()`, it does not add any attributes automatically.

#### `MeiFactory()`

Takes two arguments:

* A [template](#registering-a-template)
* The text, line or symbol object for which an element is generated by means of the template. This parameter is only of importance if [dynamic template fields](#dynamic-template-fields) are used.
* The text, line or symbol object for which an element is generated by means of the template. This parameter is only of importance if [dynamic template fields](#dynamic-template-fields) are used.

#### `AddFormattedText()`

Takes two arguments:

* `parentElement`: MEI element that the formatted text nodes should be appended to.
* `textObj`: A `Text` or `SystemTextItem` object. Its `TextWithFormatting` property is converted to MEI markup.
* `textObj`: A `Text` or `SystemTextItem` object. Its `TextWithFormatting` property is converted to MEI markup.

### Handling built-in and user-defined objects

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,14 +80,14 @@ There are two kinds of tests in two subfolders of the `test` folder:

### sib-test

These unit tests are primarily used to test specific Sibmei functions. They use the [sib-test](https://github.com/tido/sib-test) plugin, also developed by Tido. You should download and install this plugin first. After unloading and reloading the Testsibmei plugin (as described above), tests can be run by either
These unit tests are primarily used to test specific Sibmei functions. They use the [sib-test](https://github.com/tido/sib-test) plugin, also developed by Tido. You should download and install this plugin first. After unloading and reloading the Testsibmei plugin (as described above), tests can be run by either

* starting Testsibmei from the plugin editing window or
* starting "Sibmei Test Runner" from the menu/ribbon.

### mocha

[Mocha](https://mochajs.org/) is used to test Sibmei's output from a set of test files. After exporting the test file set with sibmei (Testsibmei will automatically do that), either run `npm test` from the root directory of this git repository or have Testsibmei automatically trigger the tests. The latter requires a `test.bat` or `test.sh` file in the same directory as the Sibmei `*.plg` files, depending on the operating system. Create a file that looks like this:
[Mocha](https://mochajs.org/) is used to test Sibmei's output from a set of test files. After exporting the test file set with sibmei (Testsibmei will automatically do that), either run `npm test` from the root directory of this git repository or have Testsibmei automatically trigger the tests. The latter requires a `test.bat` or `test.sh` file in the same directory as the Sibmei `*.plg` files, depending on the operating system. Create a file that looks like this:

#### Windows: test.bat

Expand Down

0 comments on commit 63a2d92

Please sign in to comment.