Pinnacle Systems Sibelius - 7.5 User Manual

Using the ManuScript language

Written by Jonathan Finn, James Larcombe, Yasir Assam, Simon Whiteside,
Mike Copperwhite, Paul Walmsley, Graham Westlake and Michael
Eastwood, with contributions from Andrew Davis and Daniel Spreadbury.

Legal Notices

This product is subject to the terms and conditions of a software license
agreement.

This guide is copyrighted © 2014 by Avid Technology Inc., (hereafter
“Avid”), with all rights reserved. Under copyright laws, this guide may not be
duplicated in whole or in part without the written consent of Avid.

Avid, Sibelius and Scorch are registered trademarks of Avid Technology,
Inc. in the USA, UK and other countries. All other trademarks are
acknowledged as the property of their respective owners.

Product features, specifications, system requirements, and availability are
subject to change without notice.

2

Contents

Introduction................................................................................................................................................................................................ 5

Tutorial 7

Edit Plug-ins................................................................................................................................................................................................8

Loops ......................................................................................................................................................................................................... 13

Objects ....................................................................................................................................................................................................... 15

Representation of a score ......................................................................................................................................................................... 17

The “for each” loop................................................................................................................................................................................... 19

Indirection, sparse arrays and user properties....................................................................................................................................... 21

Dialog editor.............................................................................................................................................................................................. 25

Debugging your plug-ins..........................................................................................................................................................................29

Storing and retrieving preferences .......................................................................................................................................................... 30

Reference 35

Syntax ........................................................................................................................................................................................................ 36

Expressions ...............................................................................................................................................................................................38

Operators................................................................................................................................................................................................... 40

Object Reference 41

Hierarchy of objects.................................................................................................................................................................................. 42

All objects ..................................................................................................................................................................................................43

Accessibility ..............................................................................................................................................................................................45

Bar..............................................................................................................................................................................................................46

Barline ....................................................................................................................................................................................................... 52

Barlines...................................................................................................................................................................................................... 53

BarObject...................................................................................................................................................................................................54

BarRest ...................................................................................................................................................................................................... 57

Bracket.......................................................................................................................................................................................................58

BracketsAndBraces...................................................................................................................................................................................59

Clef .............................................................................................................................................................................................................60

Comment...................................................................................................................................................................................................61

ComponentList ......................................................................................................................................................................................... 62

Component................................................................................................................................................................................................ 63

DateTime................................................................................................................................................................................................... 64

Dictionary.................................................................................................................................................................................................. 65

DocumentSetup ........................................................................................................................................................................................66

DynamicPartCollection............................................................................................................................................................................ 68

DynamicPart ............................................................................................................................................................................................. 69

EngravingRules......................................................................................................................................................................................... 70

File.............................................................................................................................................................................................................. 72

Folder.........................................................................................................................................................................................................73

GuitarFrame..............................................................................................................................................................................................74

GuitarScaleDiagram .................................................................................................................................................................................77

HitPointList...............................................................................................................................................................................................78

HitPoint.....................................................................................................................................................................................................79

InstrumentChange.................................................................................................................................................................................... 80

3

InstrumentTypeList..................................................................................................................................................................................81

InstrumentType........................................................................................................................................................................................ 82

KeySignature .............................................................................................................................................................................................84

Line ............................................................................................................................................................................................................ 85

LyricItem ...................................................................................................................................................................................................86

NoteRest .................................................................................................................................................................................................... 87

Note............................................................................................................................................................................................................ 90

NoteSpacingRule....................................................................................................................................................................................... 92

PageNumberChange.................................................................................................................................................................................94

PluginList ..................................................................................................................................................................................................95

Plugin......................................................................................................................................................................................................... 96

RehearsalMark ..........................................................................................................................................................................................97

Score .......................................................................................................................................................................................................... 98

Selection ..................................................................................................................................................................................................105

Sibelius..................................................................................................................................................................................................... 108

SoundInfo................................................................................................................................................................................................ 116

SparseArray............................................................................................................................................................................................. 117

Staff..........................................................................................................................................................................................................119

Syllabifier.................................................................................................................................................................................................122

SymbolItem and SystemSymbolItem....................................................................................................................................................123

SystemObjectPositions...........................................................................................................................................................................124

SystemStaff, Staff, Selection, Bar and all BarObject-derived objects.................................................................................................. 125

SystemStaff.............................................................................................................................................................................................. 126

Text and SystemTextItem ......................................................................................................................................................................127

TimeSignature......................................................................................................................................................................................... 128

TreeNode................................................................................................................................................................................................. 129

Tuplet....................................................................................................................................................................................................... 130

Utils..........................................................................................................................................................................................................131

VersionHistory........................................................................................................................................................................................ 136

Version ....................................................................................................................................................................................................137

VersionComment ................................................................................................................................................................................... 138

Global constants 139

What’s new in Sibelius 7 164

4

Introduction

ManuScript is a simple, music-based programming language developed to write plug-ins for the Sibelius music processor. The
name was invented by Ben Sloman, a friend of Ben Finn’s.

It is based on Simkin, an embedded scripting language developed by Simon Whiteside, and has been extended by him and the rest
of the Sibelius team ever since. (Simkin is a spooky pet name for Simon sometimes found in Victorian novels.) For more
information on Simkin, and additional help on the language and syntax, go to the Simkin website at www.simkin.co.uk.

Rationale

In adding a plug-in language to Sibelius we were trying to address several different issues:

*

Music notation is complex and infinitely extensible, so some users will sometimes want to add to a music notation program to
make it cope with these new extensions.

*

It is useful to allow frequently repeated operations (e.g. opening a MIDI file and saving it as a score) to be automated, using a
system of scripts or macros.

*

Certain more complex techniques used in composing or arranging music can be partly automated, but there are too many to
include as standard features in Sibelius.

There were several conditions that we wanted to meet in deciding what language to use:

*

The language had to be simple, as we want normal users (not just seasoned programmers) to be able to use it.

*

We wanted plug-ins to be usable on any computer, as the use of computers running both Windows and Mac OS X is widespread
in the music world.

*

We wanted the tools to program in the language to be supplied with Sibelius.

*

We wanted musical concepts (pitch, notes, bars) to be easily expressed in the language.

*

We wanted programs to be able to talk to Sibelius easily (to insert and retrieve information from scores).

*

We wanted simple dialog boxes and other user interface elements to be easily programmed.

C/C++, the world’s “standard” programming language(s), were unsuitable as they are not easy for the non-specialist to use, they
would need a separate compiler, and you would have to recompile for each different platform you wanted to support (and thus
create multiple versions of each plug-in).

The language Java was more promising as it is relatively simple and can run on any platform without recompilation. However, we
would still need to supply a compiler for people to use, and we could not express musical concepts in Java as directly as we could
with a new language.

So we decided to create our own language that is interpreted so it can run on different platforms, integrated into Sibelius without
any need for separate tools, and can be extended with new musical concepts at any time.

The ManuScript language that resulted is very simple. The syntax and many of the concepts will be familiar to programmers of C/
C++ or Java. Built into the language are musical concepts (Score, Staff, Bar, Clef, NoteRest) that are instantly comprehensible.

Technical support

Since the ManuScript language is more the province of our programmers than our technical support team (who are not, in the
main, programmers), we can’t provide detailed technical help on it, any more than Oracle will help you with Java programming.
This document and the sample plug-ins should give you a good idea of how to do some simple programming fairly quickly.

We would welcome any useful plug-ins you write – email them to [e-mail] and we may put them on
our web site; if we want to distribute the plug-in with Sibelius itself, we’ll pay you for it.

Mailing list for plug-in developers

There is a growing community of plug-in developers working with ManuScript, and they can be an invaluable source of help when
writing new plug-ins. To subscribe, go to http://avid-listsrv1.avid.com/mailman/listinfo/plugin-dev.

6

Tutorial

Tutorial

Edit Plug-ins

A simple plug-in

Let’s start a simple plug-in. You are assumed to have some basic experience of programming (e.g. in BASIC or C), so you’re already
familiar with ideas like variables, loops and so on.

*

Start Sibelius.

*

Choose File> Plug-ins> Edit Plug-ins. The following dialog appears:

*

Now click New.

*

You are asked to type the internal name of your plug-in (used as the plug-in’s filename), the name that should appear on the
menu and the name of the category in which the plug-in should appear, which will determine which ribbon tab it appears on.

The reason for having two separate names for plug-ins is that filenames may be no longer than 31 characters on Macs running
Mac OS 9 (which is only significant if you intend your plug-in to be used with versions of Sibelius prior to Sibelius 4), but the
menu names can be as long as you like.

*

Ty pe Tes t as the internal name, Test plug-in as the menu name and Tes ts as the category name, then click OK.

*

You’ ll se e Test (user copy) added to the list in the Edit Plug-ins dialog under a new Tes ts branch of the tree view. Click
Close. This shows the folder in which the plug-in is located (Tes ts , which Sibelius has created for you), the filename of the

plug-in (minus the standard .plg file extension), and (user copy) tells you that this plug-in is located in your user application
data folder, not the Sibelius program folder or application package itself.

*

If you look in the Home> Plug-ins gallery again you’ll see a Tes ts category, with a Tes t plug-in underneath it.

8

Edit Plug-ins

*

Choose Home> Plug-ins> Tes ts> Test and the plug-in will run. You may first be prompted that you cannot undo plug-ins,
in which case click Yes to continue (and you may wish to switch on the Don’t say this again option so that you’re not both­ered by this warning in future.) What does our new Tes t plug-in do? It just pops up a dialog which says Tes t (whenever you
start a new plug-in, Sibelius automatically generates in a one-line program to do this). You’ll also notice a window appear with a
button that says Stop Plug-in, which appears whenever you run any plug-in, and which can be useful if you need to get out of
a plug-in you’re working on that is (say) trapped in an infinite loop.

*

Click OK on the dialog and the plug-in stops.

Three types of information

Let’s look at what’s in the plug-in so far. Choose File > Plug-ins> Edit Plug-ins again, then select Tests/Test (user copy)
from the list
information that can make up a plug-in:

and click Edit (or simply double-click the plug-in’s name to edit it). You’ll see a dialog showing the three types of

*

Methods: similar to procedures, functions or routines in some other languages.

*

Dialogs: the layout of any special dialogs you design for your plug-in.

*

Data: variables whose value is remembered between running the plug-in. You can only store strings in these variables, so
they’re useful for things like user-visible strings that can be displayed when the plug-in runs. For a more sophisticated approach
to global variables, ManuScript provides custom user properties for all objects – see

User properties

on page 22.

Methods

The actual program consists of the methods. As you can see, plug-ins normally have at least two methods, which are created
automatically for you when you create a new plug-in:

*

Initialize: this method is called automatically whenever you start up Sibelius. Normally it does nothing more than add the
name of the plug-in to the Plug-ins menu, although if you look at some of the supplied plug-ins you’ll notice that it’s some­times also used to set default values for data variables.

*

Run: this is called when you run the plug-in, you’ll be startled to hear (it’s like

>

when you choose Home

Plug-ins> Te sts> Te st, the plug-in’s Run method is called. If you write any other methods, you

have to call them from the Run method – otherwise how can they ever do anything?

main()

in C/C++ and Java). In other words,

9

Tutorial

Click on Run, then click Edit (or you can just double-click Run to edit it). This shows a dialog where you can edit the Run
method:

In the top field you can edit the name; in the next field you can edit the parameters (i.e. variables where values passed to the
method are stored); and below is the code itself:

Sibelius.MessageBox("Test");

This calls a method

MessageBox

which pops up the dialog box that says Tes t when you run the plug-in. Notice that the method

name is followed by a list of parameters in parentheses. In this case there’s only one parameter: because it’s a string (i.e. text) it’s in
double quotes. Notice also that the statement ends in a semicolon, as in C/C++ and Java. If you forget to type a semicolon, you’ll
get an error when the plug-in runs.

What is the role of the word Sibelius in

Sibelius.MessageBox

? In fact it’s a variable representing the Sibelius program; the
statement is telling Sibelius to pop up the message box (C++ and Java programmers will recognize that this variable refers to an
“object”). If this hurts your brain, we’ll go into it later.

Editing the code

Now try amending the code slightly. You can edit the code just like in a word processor, using the mouse and arrow keys, and you

X

can also also use Ctrl+X/C/V or
(Mac) you get a menu with these basic editing operations on them too.

Change the code to this:

x = 1;

x = x + 1;

Sibelius.MessageBox("1 + 1 = " & x);

You can check this makes sense (or, at least, some kind of sense) by clicking the Check syntax button. If there are any blatant
mistakes (e.g. missing semicolons) you’ll be told where they are.

Then close the dialogs by clicking OK, OK again then Close. Run your amended plug-in from the Plug-ins menu and a
message box with the answer

X/C/V for cut, copy and paste respectively. If you right-click (Windows) or Control-click

1 + 1 = 2

should appear.

How does it work? The first two lines should be obvious. The last line uses

&

to stick two strings together. You can’t use + as this

works only for numbers (if you try it in the example above, you’ll get an interesting answer!).

One pitfall: try changing the second line to:

x += 1;

then click Check syntax. You’ll get an error: this syntax (and the syntax
ManuScript. You have to do

x = x+1;

.

x++

) is allowed in various languages but not in

Where plug-ins are stored

Plug-ins supplied with Sibelius are stored in folders buried deep within the Sibelius program folder on Windows, and inside the
application package (or “bundle”) on Mac. It is not intended that end users should add extra plug-ins to these locations

10

Edit Plug-ins

themselves, as we have provided a per-user location for plug-ins to be installed instead. When you create a new plug-in or edit an
existing one, the new or modified plug-in will be saved into the per-user location (rather than modifying or adding to the plug-ins
in the program folder or bundle):

*

On Windows, additional plug-ins are stored at C:\Users\username\AppData\Roaming\Avid\Sibelius 7\Plugins.

*

On Mac, additional plug-ins are stored in subfolders at /Users/username/Library/Application Support/Avid/
Sibelius 7/Plugins.

This is worth knowing if you want to give a plug-in to someone else. The plug-ins appear in subfolders which correspond to the
categories in which they appear in the various Plug-ins galleries. The filename of the plug-in itself is the plug-in’s internal name
plus the .plg extension, e.g. Te st. pl g.

>

(Sibelius includes an automatic plug-in installer, which you can access via File

Plug-ins> Install Plug-ins. This makes it

easy to download and install plug-ins from the Sibelius web site.)

Line breaks and comments

As with C/C++ and Java, you can put new lines wherever you like (except in the middle of words), as long as you remember to put
a semicolon after every statement. You can put several statements on one line, or put one statement on several lines.

//

You can add comments to your program, again like C/C++ and Java. Anything after

/*

between

and */ is ignored, whether just part of a line or several lines:

// comment lasts to the end of the line
/* you can put
several lines of comments here
*/

is ignored to the end of the line. Anything

For instance:

Sibelius.MessageBox("Hi!"); // print the active score

or:

Sibelius /* this contains the application */ .MessageBox("Hi!");

Varia bles

x

in the Test plug-in is a variable. In ManuScript a variable can be any sequence of letters, digits or _ (underscore), as long as it

doesn’t start with a digit.

A variable can contain an integer (whole number), a floating point number, a string (text) or an object (e.g. a note) – more about
objects in a moment. Unlike most languages, in ManuScript a variable can contain any type of data – you don’t have to declare
what type you want. Thus you can store a number in a variable, then store some text instead, then an object. Try this:

x = 56; x = x+1;
Sibelius.MessageBox(x); // prints '57' in a dialog box
x = "now this is text"; // the number it held is lost
Sibelius.MessageBox(x); // prints 'now this is text' in a dialog
x = Sibelius.ActiveScore; // now it contains a score
Sibelius.MessageBox(x); // prints nothing in a dialog

Variables that are declared within a ManuScript method are local to that method; in other words, they cannot be used by other
methods in the same plug-in. Global Data variables defined using the plug-in editor can be accessed by all methods in the plug­in, and their values are preserved over successive uses of the plug-in.

A quick aside about strings in ManuScript is in order at this point. Like many programming languages, ManuScript strings uses

\

the back-slash

\'

, and to include a new line you should use \n. Because of this, to include the backslash itself in a ManuScript string one has

use
to write

\\

as an “escape character” to represent certain special things. To include a single quote character in your strings,

.

Converting between numbers, text and objects

Notice that the method

MessageBox

call to

MessageBox

is expecting to be sent some text to display. If you give it a number instead (as in the first

above) the number is converted to text. If you give it an object (such as a score), no text is produced.

11

Tutorial

Similarly, if a calculation is expecting a number but is given some text, the text will be converted to a number:

x = 1 + "1"; // the + means numbers are expected

Sibelius.MessageBox(x); // displays '2'

If the text doesn’t start with a number (or if the variable contains an object instead of text), it is treated as 0:

x = 1 + "fred";

Sibelius.MessageBox(x); // displays ‘1’

12

Loops

“for” and “while”

ManuScript has a
plug-in called Potato. This is going to amuse one and all by writing the words of the well-known song “1 potato, 2 potato, 3
potato, 4”. Type in the following for the Run method of the new plug-in:

x = 1;
while (x<5)
{

}

Run it. It should display “1 potato,” “2 potato,” “3 potato,” “4 potato,” which is a start, though annoyingly you have to click OK after
each message.

while

The
semicolon after the final
compulsory (you can’t omit them if they only contain one statement). Moreover, each block must contain at least one statement.
We did say that ManuScript was a simple language.

while

loop which repeatedly executes a block of code until a certain expression becomes True. Create a new

text = x & " potato,";
Sibelius.MessageBox(text);
x = x+1;

statement is followed by a condition in

}

brace). While the condition is true, the block is executed. Unlike some other languages, the braces are

( )

parentheses, then a block of statements in

{ }

braces (you don’t need a

Loops

x

In this example you can see that we are testing the value of
common construct could be expressed more concisely in ManuScript by using a

at the start of the loop, and increasing the value at the end. This

for

loop. The above example could also be

written as follows:

for x = 1 to 5
{

text = x & " potato,";
Sibelius.MessageBox(text);

}

Here, the variable x is stepped from the first value (1) up to the end value (5), stopping one step before the final value. By default,
the “step” used is 1, but we could have used (say) 2 by using the syntax

for x = 1 to 5 step 2

, which would then print

only “1 potato” and “3 potato”!

&

Notice the use of

to add strings. Because a string is expected on either side, the value of x is turned into a string.

Notice also we’ve used the Tab key to indent the statements inside the loop. This is a good habit to get into as it makes the
structure clearer. If you have loops inside loops you should indent the inner loops even more.

The if statement

Now we can add an if statement so that the last phrase is just “4,” not “4 potato”:

x = 1;
while (x<5)
{

if(x=4)
{

text = x & ".";
}
else
{

text = x & " potato,";
}
Sibelius.MessageBox(text);
x = x+1;

}

13

Tutorial

if

The rule for

takes the form

executed if the condition is false. As with

if (

condition

while

) {

statements}. You can also optionally add

, the parentheses and braces are compulsory, though you can make the program

shorter by putting braces on the same line as other statements:

x = 1;
while (x<5)
{

if(x=4) {

text = x & ".";
} else {

text = x & " potato,";
}
Sibelius.MessageBox(text);
x = x+1;

}

The position of braces is entirely a matter of taste.

Now let’s make this plug-in really cool. We can build up the four messages in a variable called

if

and

saving valuable wear on your mouse button. We can also switch round the

for

we return to the

text = ""; // start with no text
for x = 1 to 5
{

if (not(x=4)) {

} else {

}

}

syntax we looked at earlier.

text = text & x & " potato, "; // add some text

text = text & x & "."; // add no. 4

else

else {

text

, and only display it at the end,

statements}, which is

blocks to show off the use of

not

. Finally,

Sibelius.MessageBox(text); // finally display it

Arithmetic

We’ve been using + without comment, so here’s a complete list of the available arithmetic operators:

a + b

a - b

a * b

a / b

a % b

-a

(a)

ManuScript evaluates operators strictly from left-to-right, unlike many other languages; so
might expect. To get the answer 14, you’d have to write

ManuScript also supports floating point numbers, so whereas in some early versions

1.5. Conversion from floating point numbers to integers is achieved with the

Round(

expr)functions, which can be applied to any expression.

add

subtract

multiply

divide

remainder

negate

evaluate first

2+(3*4)

.

3/2

would work out as 1, it now evaluates to

RoundUp(

2+3*4

evaluates to 20, not 14 as you

expr),

RoundDown(

expr) and

14

Objects

Now we come to the neatest aspect of object-oriented languages like ManuScript, C++ or Java, which sets them apart from
traditional languages like BASIC, Fortran and C. Variables in traditional languages can hold only certain types of data: integers,
floating point numbers, strings and so on. Each type of data has particular operations you can do to it: numbers can be multiplied
and divided, for instance; strings can be added together, converted to and from numbers, searched for in other strings, and so on.
But if your program deals with more complex types of data, such as dates (which in principle you could compare using
convert to and from strings, and even subtract) you are left to fend for yourself.

Object-oriented languages can deal with more complex types of data directly. Thus in the ManuScript language you can set a
variable, let’s say

thischord.AddNote(60); // adds middle C (note no. 60)
thischord.AddNote(64); // adds E (note no. 64)

thischord

, to be a chord in your score, and (say) add more notes to it:

If this seems magic, it’s just analogous to the kind of things you can do to strings in BASIC, where there are very special operations
which apply to text only:

A$ = "1"
A$ = A$ + " potato, ": REM add strings
X = ASC(A$): REM get first letter code

In ManuScript you can set a variable to be a chord, a note in a chord, a bar, a staff or even a whole score, and do things to it. Why
would you possibly want to set a variable to be a whole score? So you can save it or add an instrument to it, for instance.

=, <

Objects

and >,

Objects in action

We’ll have a look at how music is represented in ManuScript in a moment, but for a little taster, let’s plunge straight in and adapt
Potato to create a score:

x = 1;
text = ""; // start with no text
while (x<5)
{

if (not(x=4)) {

text = text & x & " potato, "; // add some text
} else {

text = text & x & "."; // add no. 4
}
x = x+1;

}

Sibelius.New(); // create a new score
newscore = Sibelius.ActiveScore; // put it in a variable
newscore.CreateInstrument("Piano");
staff = newscore.NthStaff(1); // get top staff
bar = staff.NthBar(1); // get bar 1 of this staff
bar.AddText(0,text,"Technique"); // use Technique text style

This creates a score with a Piano, and types our potato text in bar 1 as Technique text.

The code uses the period (
that the variable before the period has to contain an object.

.

) several times, always in the form

variable.variable

or

variable.method()

. This shows

*

If there’s a variable name after the period, we’re getting one of the object’s sub-variables (called “fields” or “member variables” in

n

some languages). For instance, if
60 for middle C), and

n.Name

is a variable containing a note, then

is a string describing its pitch (e.g. “C4” for middle C). The variables available for each type of

n.Pitch

is a number representing its MIDI pitch (e.g.

object are listed later.

*

If there’s a method name after the period (followed by () parentheses), one of the methods allowed for this type of object is
called. Typically a method called in this way will either change the object or return a value. For instance, if s is a variable con-

15

Tutorial

taining a score, then

s.CreateInstrument("Flute")

adds a flute (changing the score), but

s.NthStaff(1)

returns

a value, namely an object containing the first staff.

Let’s look at the new code in detail. There is a pre-defined variable called Sibelius, which contains an object representing the
Sibelius program itself. We’ve already seen the method

Sibelius.MessageBox()

. The method call

Sibelius.New()

tells

Sibelius to create a new score. Now we want to do something to this score, so we have to put it in a variable.

Fortunately, when you create a new score it becomes active (i.e. its title bar highlights and any other scores become inactive), so
we can just ask Sibelius for the active score and put it in a variable:

newscore = Sibelius.ActiveScore.

Then we can tell the score to create a Piano: newscore.CreateInstrument("Piano"). But to add some text to the
score you have to understand how the layout is represented.

16

Representation of a score

Representation of a score

A score is treated as a hierarchy: each score contains 0 or more staves; each staff contains bars (though every staff contains the
same number of bars); and each bar contains “bar objects.” Clefs, text and chords are all different types of bar objects.

So to add a bar object (i.e. an object which belongs to a bar), such as some text, to a score: first you have to get which staff you
want (and put it in a variable):
(and put it in a variable):

bar.AddText(0,text,"Technique")

staff = newscore.NthStaff(1)

bar = staff.NthBar(1)

. You have to give the name (or index number – see

the text style to use (and it has to be a staff text style, because we’re adding the text to a staff).

Notice that bars and staves are numbered from 1 upwards; in the case of bars, this is irrespective of any bar number changes that
are in the score, so the numbering is always unambiguous. In the case of staves, the top staff is no.1, and all staves are counted,
even if they’re hidden. Thus a particular staff has the same number wherever it appears in the score.

; then you have to get which bar in that staff you want

; finally you tell the bar to add the text:

Text styl e s

on page 141) of

The

AddText

method for bars is documented later, but the first parameter it takes is a rhythmic position in the bar. Each note in

a bar has a rhythmic position that indicates where it is (at the start, one quarter after the start, etc.), but the same is true for all
other objects in bars. This shows where the object is attached to, which in the case of Technique text is also where the left hand
side of the text goes. Thus to put our text at the start of the bar, we used the value 0. To put the text a quarter note after the start of
the bar, use 256 (the units are 1024th notes, so a quarter is 256 units – but don’t think about this too hard):

bar.AddText(256,text,"Technique");

To avoid having to use obscure numbers like 256 in your program, there are predefined variables representing different note
values (which are listed later), so you could write:

bar.AddText(Quarter,text,"Technique");

or to be quaint you could use the British equivalent:

bar.AddText(Crotchet,text,"Technique");

For a dotted quarter, instead of using 384 you can use another predefined variable:

bar.AddText(DottedQuarter,text,"Technique");

or add two variables:

bar.AddText(Quarter+Eighth,text,"Technique");

This is much clearer than using numbers.

The system staff

As you know from using Sibelius, some objects don’t apply to a single staff but to all staves. These include titles, tempo text,
rehearsal marks and special barlines; you can tell they apply to all staves because (for instance) they get shown in all the
instrumental parts.

All these objects are actually stored in a hidden staff, called the system staff. You can think of it as an invisible staff which is always
above the other staves in a system. The system staff is divided into bars in the same way as the normal staves. So to add the title
“Potato” to our score we’d need the following code in our plug-in:

sys = newscore.SystemStaff; // system staff is a variable
bar = sys.NthBar(1);
bar.AddText(0,"POTATO SONG","Subtitle");

As you can see,

SystemStaff

is a variable you can get directly from the score. Remember that you have to use a system text
style (here I’ve used Subtitle) when putting text in a bar in the system staff. A staff text style like Technique won’t work. Also, you
have to specify a bar and position in the bar; this may seem slightly superfluous for text centered on the page as titles are (though
in reality even this kind of page-aligned text is always attached to a bar), but for Tempo and Metronome mark text they are
obviously required.

17

Tutorial

Representation of notes, rests, chords and other musical items

Sibelius represents rests, notes and chords in a consistent way. A rest has no noteheads, a note has 1 notehead and a chord has 2 or
more noteheads. This introduces an extra hierarchy: most of the squiggles you see in a score are actually a special type of bar
object that can contain even smaller things (namely, noteheads). There’s no overall name for something which can be a rest, note
or chord, so we’ve invented the pretty name NoteRest. A NoteRest with 0, 1 or 2 noteheads is what you normally call a rest, a note
or a chord, respectively.

If n is a variable containing a NoteRest, there is a variable

n.Duration

highest and lowest notes (assuming
about the lowest note, such as
methods and variables may be found in the

which is the note-value in 1/256ths of a quarter. You can also get

n.NoteCount

lownote.Pitch

Reference

isn’t 0). If you set

(a number) and

section below.

n.NoteCount

lownote = n.Lowest

lownote.Name

which contains the number of notes, and

n.Highest

and

n.Lowest

which contain the

, you can then find out things

(a string). Complete details about all these

Other musical objects, such as clefs, lines, lyrics and key signatures have corresponding objects in ManuScript, which again have
various variables and methods available. For example, if you have a Line variable

, then

ln.EndPosition

gives the

ln

rhythmic position at which the line ends.

18

The “for each” loop

The “for each” loop

It’s a common requirement for a loop to do some operation to every staff in a score, or every bar in a staff, or every BarObject in a
bar, or every note in a NoteRest. There are other more complex requirements which are still common, such as doing an operation
to every BarObject in a score in chronological order, or to every BarObject in a multiple selection. ManuScript has a
loop that can achieve each of these in a single statement.

for each

The simplest form of

thisscore = Sibelius.ActiveScore;
for each s in thisscore // sets s to each staff in turn
{

// ...do something with s

}

Here, since

thisscore

because staves are the type of object at the next hierarchical level of objects (see

for each

is like this:

is a variable containing a score, the variable s is set to be each staff in

Hierarchy of objects

thisscore

on page 42). For each

in turn. This is

staff in the score, the statements in {} braces are executed.

Score objects contain staves, as we have seen, but they can also contain a Selection object, e.g. if the user has selected a passage of
music before running the plug-in. The Selection object is a special case: it is never returned by a
only a single selection object; if you use the Selection object in a

for each

loop, by default it will return BarObjects (not Staves,

for each

loop, because there is

Bars or anything else!).

Let’s take another example, this time for notes in a NoteRest:

noterest = bar.NthBarObject(1);
for each n in noterest // sets n to each note in turn
{

Sibelius.MessageBox("Pitch is " & n.Name);

}

is set to each note of the chord in turn, and its note name is displayed. This works because Notes are the next object down the

n

hierarchy after NoteRests. If the NoteRest is, in fact, a rest (rather than a note or chord), the loop will never be executed – you
don’t have to check this separately.

The same form of loop will get the bars from a staff or system staff, and the BarObjects from a bar. These loops are often nested, so
you can, for instance, get several bars from several staves.

This first form of the
second form of the

for each

for each

loop got a sequence of objects from an object in the next level of the hierarchy of objects. The

loop lets you skip levels of the hierarchy, by specifying what type of object you want to get. This

saves a lot of nested loops:

thisscore = Sibelius.ActiveScore;
for each NoteRest n in thisscore
{

n.AddNote(60); // add middle C

}

By specifying

NoteRest

after

for each

, Sibelius knows to produce each NoteRest in each bar in each staff in the score;
otherwise it would just produce each staff in the score, because a Staff object is the type of object at the next hierarchical level of
objects. The NoteRests are produced in a useful order, namely from the top to the bottom staff, then from left to right through the
bars. This is chronological order. If you want a different order (say, all the NoteRests in the first bar in every staff, then all the
NoteRests in the second bar in every staff, and so on) you’ll have to use nested loops.

So here’s some useful code that doubles every note in the score in octaves:

19

Tutorial

score = Sibelius.ActiveScore;
for each NoteRest chord in score
{

if(not(chord.NoteCount = 0)) // ignore rests
{

note = chord.Highest; // add above the top note
chord.AddNote(note.Pitch+12); // 12 is no. of half-steps (semitones)

}

}

It could easily be amended to double in octaves only in certain bars or staves, only if the notes have a certain pitch or duration, and
so on.

This kind of loop is also very useful in conjunction with the user’s current selection. This selection can be obtained from a variable
containing a Score object as follows:

selection = score.Selection;

We can then test whether it’s a passage selection, and if so we can look at (say) all the bars in the selection by means of a

loop:

each

if (selection.IsPassage)
{

for each Bar b in selection
{

// do something with this bar
…

}

}

for

Be aware that you can not add or remove items from bars during iterating. The example of adding notes to chords above is fine
because you are modifying an existing item (in this case a NoteRest), but it’s not safe to add or remove entire items, and if you try
to do so, your plug-in will abort with an error. However, it’s very useful to add or remove items from bars, so you need to do that in

for

a separate

loop, after first collecting the items you want to operate on into a ManuScript array, something like this:

num = 0;
for each obj in selection
{
if (IsObject(obj))
{
n = "obj" & num;
@n = obj;
num = num + 1;
}
}
selection.Clear();
for i = 0 to num
{
n = "obj" & i;
obj = @n; // get an object from the pseudo array
obj.Select();
}

The @n in this example is the array. To find out more about arrays, read on.

20

Indirection, sparse arrays and user properties

Indirection, sparse arrays and user properties

Indirection

If you put the @ character before a string variable name, then the value of the variable is used as the name of a variable or method.
For instance:

var="Name";
x = @var; // sets x to the contents of the variable Name

mymethod="Show";
@mymethod(); // calls the method Show

This has many advanced uses, though if taken to excess it can cause the brain to hurt. For instance, you can use @ to simulate

name

“unlimited” arrays. If
Thus:

i = 10;
name = "x" & i;
@name = 0;

is a variable containing the string

"x1"

, then

@name

is equivalent to using the variable x1 directly.

sets variable

x10

to 0. The last two lines are equivalent to

x[i] = 0;

in the C language. This has many uses; however, you’ll

also want to consider using the built-in arrays (and hash tables), which are documented below.

Sparse arrays

The method described above can be used to create “fake” arrays through indirection, though this is a little fiddly. ManuScript also
provides Javascript-style sparse arrays, which can store anything that can be stored in a ManuScript variable, including references
to objects. Like a variable, storing a reference to an object in a sparse array will preserve the lifetime of that object (because objects
are reference counted), but the underlying object in Sibelius may become invalid if (say) a Score is modified.

To create a sparse array in ManuScript, use the built-in method
empty array simply by passing in no variables to the

Sparse arrays provide a read/write variable called

CreateSpareArray

Length

CreateSparseArray(a1,a2,a3,

method.

that returns or sets the length of the array: when you set
number greater than the present size of the array, the array is padded with null values; if you set
than the present size of the array, any values beyond this number are removed.

To push one or more values to the end of the array, use the method

Pop()

of an array, use the method

.

Push(a1,

a2, ... an). To remove and return the last element

An example of how to use a sparse array:

array = CreateSparseArray(4,5,6);
array[10] = 19; // creates 11th element of array, intervening elements are null
array.Length = 20; // extends array to 20 elements, new elements are all null

Sparse arrays by their nature may not have values in every array element. To return a new sparse array containing only the
populated indices of the original sparse array (i.e. those that are not null), use the array’s

ValidIndices

using the above sparse array:

a4...an). You can create an

Length

Length

to a number smaller

variable. For example,

to a

array2 = array.ValidIndices; // will contain values 0, 1, 2, 10 and 19
return array[array2[0]]; // returns the first populated element of array

You can compare two sparse arrays for equality, e.g.:

if (array = array2) {

// do something

}

To access the end of an array, it’s convenient to use negative indices; e.g.

array[-1]

returns the last element,

array[-2]

returns the penultimate element, and so on. It’s not possible to access elements before the start of the array, so if you do e.g.

array[-100]

on a six element array, you will get

array[0]

returned.

21

Tutorial

Some things to remember when using sparse arrays:

*

Sparse arrays use a zero-based index.

*

Elements that have not been initialised are null, and do not cause an error when referenced.

*

Assigning to an index beyond the current length increases the

*

If an array contains references to objects, whether the arrays are equal or not depends on the implementation of equality for

Length

to one greater than the index assigned to.

those objects.

User properties

All ManuScript objects other than those listed below, including objects created by Sibelius, can have user properties attached to
them, allowing for convenient storage of extra data, encapsulation of several items of data within a single object, and returning
more than one value from a method, among other things.

To create a new user property, use the following syntax:

._property:

object

property_name

=

value

;

where object is the name of the object, property_name is the desired user property name, and value is the value to be assigned to
the new user property. User properties are read/write and can be accessed as object

.

property_name.

To get a sparse array containing the names of all the user properties belonging to an object, you can do e.g.:

names = object._propertyNames;

Here is an example of creating a user property:

nr = bar.NoteRest;
nr._property:original = true;
if (nr.original = true) {

// do something

}

Some things to remember when using user properties:

*

If you attempt to get or set a user property that has not yet been created, your plug-in will exit with a run-time error.

*

To check whether or not a user property has been created without causing a run-time error, use the notation

._property:

object

*

User properties cannot be created or accessed for normal data types (e.g. strings, integers, etc.), the global
old-style ManuScript arrays created by

*

User properties that conflict with an existing property name cannot be accessed as
be accessed using the

*

User properties belong to a particular ManuScript object and disappear when that object’s lifetime ends. To stop an object

property_name, which will be null if no matching user property has been created yet.

._property:

CreateArray()

notation).

, old-style hashes created by

object.

CreateHash()

property_name (though they can

Sibelius

, and null.

object,

dying, you can (for example) store it in a sparse array, but be aware that its contents may become invalid if (say) the underlying
score changes.

Dictionary

Dictionary

construction. It also has methods allowing the use of aribtrarily named user properties, and can also have methods in plug-ins
attached to it allowing the creation of encapsulated user objects (i.e. objects with variables and methods attached to them).

To create a dictionary, use the built-in function
This creates a dictionary containing user properties called name1, name2, nameN with values value1, value2, valueN respectively.

A dictionary can contain named data items (like a
can use strings to look items up within it.

The values in a dictionary can be accessed using square bracket notation, so you can use a dictionary like a hash table, e.g.:

22

is a programmer extensible object, simply allowing the use of user properties as above with convenient

CreateDictionary(

struct

test = CreateDictionary("fruit",apple,"vegetable",potato);
test["fruit"] = banana;
test["meat"] = lamb;

in languages like C++), or data that is indexed by string, so that you

name1, value1, name2, value2, ... nameN, valueN).

Indirection, sparse arrays and user properties

You can even put other objects, e.g. sparse arrays, inside dictionaries, e.g.

test2 = CreateDictionary("fruit", CreateSparseArray(apple,banana,orange));

You can access the user properties within a dictionary using the

return test2._property:fruit;

._property:

notation, e.g.:

which would return the array specified above. Even more direct, you can access user properties in a dictionary as if they were
variables or methods, like this:

test2.fruit;

which would also return the array specified above. You can also return more than one value from any ManuScript method using a
dictionary, e.g.:

getChord()
value = CreateDictionary("a", aNote, "b", anotherNote);
return value;

//... in another method somewhere
chord = getChord();
trace(chord.a);
trace(chord.b);

which returns two values, a and b, which you can access via e.g.

chord.a

and

chord.b

.

You can compare two dictionaries for equality, e.g.:

if (test2 = test3) {
// do something
}

Whether or not dictionaries containing objects evaluate as equal depends on the implementation of equality for those objects.

If you’re comfortable with programming in general, you may find it useful to be able to add methods to dictionaries, particularly
if you are writing code designed to act as a library for other methods or plug-ins to call. Writing code in this way provides a degree
of encapsulation and can make it easy for client code to use your library.

To add a method to a dictionary, call the dictionary’s

pluginmethod "(obj,x,y) {
// a method that does something to obj
}"
test4 = CreateDictionary();
test4.SetMethod("doSomething",Self,"pluginmethod");
test4.doSomething(3,4); // call pluginmethod within the current plug-in, passing in
// test4 (obj in the method above) and 3 (x in the method
// above) and 4 (y in the method above)

In the example above,
method is defined in the same plug-in, and

doSomething

is the name of the method belonging to the dictionary,

pluginmethod

SetMethod()

is the name of a method elsewhere in the plug-in (shown at the top

method, e.g.:

Self

tells the plug-in that the

of the example).

To return a sparse array containing the names of the methods belonging to a dictionary, use the dictionary’s

GetMethodNames()
MethodExists()

method. You can also check the existence of a particular method using the dictionary’s

method. Use the dictionary’s

CallMethod()

method to call a specific method, where the name of the

method is the first parameter, and any parameters to be passed to the specified method follow. For example:

array = test4.GetMethodNames(); // create sparse array containing method names
first_method_name = array[0]; // sets first_method_name to name of first method
methodfound = test4.MethodExists("doSomething"); // returns True in this case;
test4.CallMethod("doSomething",5,6);

Everything you put into a dictionary is a user property, so all of the methods outlined in
data in dictionaries too.

User properties

above can be used on

23

Tutorial

Using user properties as global variables

You ca n s t o r e
itself. In the example below,
assigned to the plug-in, containing a Dictionary:

User properties assigned to the plug-in are persistent between invocations. Take care to ensure that these user properties are
created before you attempt to use them, otherwise your plug-in will abort with a run-time error. Using the

_property:

if property_name hasn't been created yet.

SparseArray

Self._property:globalData = CreateDictionary(1,2,3,4);
// globalData and Self.globalData can be used interchangeably
trace(globalData);
trace(Self.globalData);

and

Dictionary

Self

is the object that corresponds to the running plug-in, and a user property

objects, and indeed any other object, as user properties of the Plugin object

globalData

property_name syntax never causes run-time errors, but direct references to property_name force a runtime error

is

The example below shows how to test the existence of a specific user property,

globalCounter

, initialise it to 0 if it is not

found, then increment it by 1 every time the plug-in runs:

// Test the persistence of user properties
if (Self._property:globalCounter = null) {
Self._property:globalCounter = 0;
}
globalCounter = globalCounter + 1;
// this number increases by one every time the plugin is run
trace(globalCounter);
trace(Self.globalCounter);

If you store a reference to a musical object in a user property that is assigned to the plug-in, there is an increased danger of that
reference becoming invalid due to the score being closed or edited, etc. Use the

IsValid()

method to validate such data before

using it.

User properties of plug-ins will be inaccessible (except by using the

_property:

property_name syntax) if there is an existing

global variable of the same name.

Watch out for recursive cycles!

Be careful not to create recursive cycles using arrays, user properties and dictionaries. When you use, say, an array in a dictionary,
you are not creating a copy of the array or its values, but a reference to the original array: dictionaries and arrays are objects, not
values. As a result, you could write something where an array contains a dictionary that itself refers to the original array: this will
lead to Sibelius crashing. So be careful!

Other things to look out for

The Parallel 5ths and 8ves plug-in illustrates having several methods in a plug-in, which we haven’t needed so far. The
Proof-read plug-in illustrates that one plug-in can call another – it doesn’t do much itself except call the CheckPizzicato,
CheckSuspectClefs, CheckRepeats and CheckHarpPedaling plug-ins. Thus you can build up meta-plug-ins that use

libraries of others. Cool!

(You object-oriented programmers should be informed that this works because, of course, each plug-in is an object with the same
powers as the objects in a score, so each one can use the methods and variables of the others.)

24

Dialog editor

Radio button

Checkbox

Button

Static text

Editable text

Combo box

List box

Group box

Dialog editor

For more complicated plug-ins than the ones we’ve been looking at so far, it can be useful to prompt the user for various settings
and options. This may be achieved by using ManuScript’s simple built-in dialog editor. Dialogs can be created in the same way as
methods and data variables in the plug-in editor.

Showing a dialog in a plug-in

To show a dialog from a ManuScript method, we use the built-in call

Sibelius.ShowDialog(dialogName, Self);

where dialogName is the name of the dialog we wish to show, and

Self

is a “special” variable referring to this plug-in (telling

Sibelius to whom the dialog belongs). Control will only be returned to the method once the dialog has been closed by the user.

Creating or editing a dialog

To create a new dialog, choose the Dialog radio button at the bottom of the window that lists methods, data and dialogs, and
click Add. To edit an existing dialog, select it from the Dialogs list box at the top right-hand corner of the window, and click
Edit.

The dialog form will then appear, along with a long thin “palette” of available controls, as follows:

To create a new control, simply drag and drop it from the palette onto the dialog.

Dialog properties

With no controls selected, either double-click on a blank part of the dialog (or right-click, and then choose Properties) to access
the dialog’s Properties dialog, which allows you to specify:

*

Name: the value of dialogName for the

Sibelius.ShowDialog()

method call (see

Showing a dialog in a plug-in

above).

*

Title: the name of the dialog as it appears in its title bar.

*

Size: the Width and Height (measured in somewhat arbitrary dialog units); you can also set the size of the dialog by resizing
it directly when editing it.

*

Position: the X and Y position that the dialog should open at by default.

Laying out controls

The dialog editor includes a number of simple options for producing a pleasing layout:

*

To select a control, either click it or hit Tab to select the next control in the creation order (Shift-Tab selects the previous control).

*

To nudge a selected control, simply use the arrow keys.

*

To align controls, select them using Ctrl+click (Windows) or X-click (Mac), then use e.g. Ctrl+0 or X0 to align all of the

3

selected controls with the left-hand edge of the left-most control, or Ctrl+
top edge of the top-most control.

*

To space controls evenly, select them using Ctrl+click (Windows) or X-click (Mac), then use e.g. Ctrl+Shift+Alt+2 or

xzX2

most controls, or Ctrl+Shift+Alt+

to space the controls evenly in the distance between the top edge of the top-most and the bottom edge of the bottom-

0

or

xzX0

to space the controls evenly in the distance between the left-hand edge of the

or X3 to align all of the selected controls with the

25

Tutorial

left-most and the right-hand edge of the right-most controls. Once controls are spaced evenly, you can increase or decrease the
space between them proportionally by typing Ctrl+Shift+Alt+

3/2/0/1

or

xzX3/2/0/1

as appropriate.

You can optionally display a grid to aid with alignment. Right-click on a blank part of the dialog and choose Grid from the
context menu to see a dialog with settings for the grid:

Switch on Show grid to show the grid in the editor. Choose between Dots or Lines, and specify the Opacity of the grid
display by adjusting the slider. Switch on Snap to grid to enable control snapping as you drag them with the mouse. Although a
control that you nudge with the keyboard will not snap to the grid, one side of its selection outline will flash when it comes into
alignment with the grid in either the horizontal or vertical directions.

Undo and redo

You can undo and redo everything you have done while editing a dialog using Ctrl+Z or XZ to undo and Ctrl+Y or XY to redo.

Testing your dialog

To test your dialog within the editor, right-click a blank part of the dialog and choose Test from the context menu (or type the

X

shortcut Ctrl+T or

T). To finish testing and return to the editor, simply hit Esc, or click any control whose properties are set to

close the dialog (e.g. an OK or Cancel button, if you have created one).

Saving your changes

To save the changes to your dialog, simply click the close button in the dialog’s title bar: if you have any unsaved changes, Sibelius
will ask you whether or not to save the changes.

Set Creation Order

If you have done any programming in other languages that allow you to edit dialogs, you will probably be familiar with the
concept of tab order, which refers to the order in which controls are given the focus when the user repeatedly hits the Tab key to
cycle through them. ManuScript has a similar concept called creation order, so named because the order in which the controls in a
dialog are created affects not only the tab order but also some other subtle things (including radio button grouping – see

buttons

To set the creation order of controls in your plug-in’s dialog, right-click on a blank part of the dialog and choose Set Creation
Order from the context menu. A special display appears overlaid on the controls in your dialog, like this:

below).

Radio

To set the creation order, simply click on each control in order. If you make a mistake, hold down Ctrl or
control whose order is correct to restart the sequence from that point, then release Ctrl or
remaining controls. Once you’re done, hit Esc to finish editing the creation order.

26

X

and click on the last

X

and resume clicking on the

Control properties

Every control that you create also has a Properties dialog, which can be accessed by
double-clicking a selected control (or by right-clicking and choosing Properties from the

X

context menu, or by typing the shortcut Ctrl+Return or
radio button control, for example, is shown on the right.

With a control selected, the properties window varies depending on the type of the control,
but most of the options are common to all controls, and these are as follows:

*

ID: an internal string that identifies the control; Sibelius generates this for you
automatically, but you can change if you like

*

Tex t: the text appearing in the control

*

Position (X, Y): where the control appears in the dialog, in coordinates relative to the
top left-hand corner

*

Size (width, height): the size of the control

*

Variable storing control’s value: the ManuScript Data variable that will corre-
spond to the value of this control when the plug-in is run

*

Method called when clicked: the ManuScript method that should be called whenever the user clicks on this control (leave
blank if you don’t need to know about users clicking on the control)

*

Click closes dialog: select this option if you want the dialog to be closed whenever the user clicks on this control. The addi-
tional options Returning True / False specify the value that the
the window is closed in this way.

*

Give this control focus: select this option if the “input focus” should be given to this control when the dialog is opened, i.e.
if this should be the control to which the user’s keyboard applies when the dialog is opened. Mainly useful for editable text
controls.

-Return). The dialog for a

Sibelius.ShowDialog

method should return when

Dialog editor

Other options vary according to the type of control selected.

Combo boxes and list boxes

Combo boxes and list boxes have an additional property; you can set a variable from which the control’s list of values should be
taken. Like the value storing the control’s current value, this should be a global Data variable. However, in this instance they have
a rather special format, to specify a list of strings rather than simply a single string. Look at the variable

_ComboItems

String Fingering for an example – it looks like this:

_ComboItems
{

"1"
"2"
"3"
"4"
"1 and 3"
"2 and 4"

}

List boxes have one further property, which is to determine whether they should allow a single selection or multiple selections.
The return value from a combo box or a single-selection list box is a single string. If a list box is set to allow multiple selections,
the selection is returned as an array of strings.

Radio buttons

Radio buttons also have an additional property that allows one to specify groups of radio buttons in plug-in dialogs. When the
user clicks on a radio button in a group, only the other radio buttons belonging to that groups are deselected; any others in the
dialog are left as they are. This is extremely useful for more complicated dialogs.

in Add

To specify a radio group, pick one control from each group that represents the first button of the group, and for these controls
ensure that the checkbox Start a new radio group is selected in the control’s Properties dialog. Then set the creation order
of the controls (see

Set Creation Order

above). A radio button group is defined as being all the radio buttons created between

27

Tutorial

two buttons that have the Start a new radio group flag set (or between one of these buttons and the end of the dialog). So to
make the radio groups work properly, ensure that each group is created sequentially in order, with the button at the start of the
group created first, and then all the rest of the radios in that group. To finish, click the Set Creation Order menu item again to
deactivate this mode.

Static text

Static text controls additionally allow you to determine whether the text should be aligned to the Left (useful for explanatory text)
or to the Right (useful for text associated with a specific control to its right, such as an edit control, checkbox or combo box).

Buttons

In most plug-in dialogs, you will want the OK button to be the default button for the dialog, such that if the user hits Return or
Enter on their keyboard, the dialog is confirmed, and closes. Likewise, you will want the Cancel button to respond to the user

hitting Esc on their keyboard, closing the dialog without making any changes.

For OK buttons, or other buttons that should confirm the dialog, switch on the Default button for dialog checkbox in the
button’s Properties dialog. Each dialog should only have one default button. You will also normally set Click closes dialog,

returning to Tr ue. Depending on the other controls in your dialog, you may additionally want to check Give this control
focus; if you have one or more edit controls in the dialog, you should probably set Give this control focus on the first of

those controls instead.

Cancel buttons, by contrast, should normally only have Click closes dialog, returning set to False.

28

Debugging your plug-ins

When developing any computer program, it’s all too easy to introduce minor (and not so minor!) mistakes, or bugs. ManuScript
performs its own internal error checking at all times, and you’ll find that if you try to access a non-existent method or variable on
an object, or make a syntax error, or attempt to add or remove bars or items from bars while iterating over them, the plug-in will
throw an error and open the plug-in editor window at the line that generated the error.

As ManuScript is a simple, lightweight system, there is no special purpose debugger, but there are a handful of tools provided to
help you debug your plug-ins.

Undo

One good technique for finding problems in your plug-ins is to set Sibelius’s undo buffer to a very small size, or to disable it
altogether (by dragging the slider on the Other page of File
ManuScript does not throw an error when you perform an illegal operation (e.g. adding or deleting an object while iterating over
a bar), reducing the undo buffer to its smallest possible size will expose the problem right away – though be warned, the result of
such a problem may well be that Sibelius will crash.

Plug-in Trace Window

The trace window can be shown by choosing Plug-ins> Plug-in Trace Window. A special ManuScript command,

trace(

particular points. These commands can then be removed when you’ve finished debugging. Another useful feature of the trace
window is function call tracing. When this is turned on, the log will show which functions are being called by plug-ins.

string), will print the specified string in the trace window. This is useful to keep an eye on what your plug-in is doing at

>

Preferences to its leftmost position). In the unlikely event that

One potential pitfall with the

trace(

string) approach to debugging is that the built-in hash table and array objects discussed

earlier aren’t strings, and so can’t be output to the trace window. To avoid this problem, both of these objects have a corresponding
method called

WriteToString()

, which returns a string representing the whole structure of the array or hash at that point. So

we could trace the current value of an array variable as follows:

trace("array variable = " & array.WriteToString());

Checking the validity of objects

One of the common problems that you might encounter when writing complex plug-ins is that the object you are trying to operate
on is no longer valid (e.g. it has already been deleted). You can enable error checking – either for all objects, or for individual
objects – that will cause your plug-in to throw an error if an object is no longer valid.

To enable error checking, use the ManuScript command

true

Boolean parameter enable to

. If enable is the only parameter, validation checking is enabled for all types of objects, and all

plug-ins. If you supply one or more object parameters (e.g.

ValidationChecking(

Tuplet, Score, BarObject

checked, and only in the currently running plug-in. You should ensure

ValidationChecking

enable[, object1[, object2]...]), and set the

, etc.), only those objects will be

is set to

false

before you give

your plug-ins to anybody else to use.

You can also use the special method
question no longer exists.

GetValidationError(

error has occurred, so you can do e.g.

IsValid()

trace(GetValidationError(score));

to determine whether an object is valid: it will return

false

if the object in

object) returns an empty string if there is no error, or returns a string if an

to trace any validation error returned by a

Score object to the trace window.

Stopping the plug-in

If you want to force your plug-in to stop on a particular error condition, use the method
stop your plug-in, display the optional message in an alert box, and open the plug-in editor at the line of code reached.

StopPlugin(

[message]), which will

You ca n als o u se

ExitPlugin()

, which exits the plug-in cleanly without dropping into the plug-in editor.

Tutorial

Storing and retrieving preferences

In Sibelius 4 or later, you can use Preferences.plg, contributed by Hans-Christoph Wirth, to store and retrieve user-set
preferences for your plug-ins.

How does it work?

Preferences.plg stores its data in a text file in the user’s application data folder. Strings are accessed as associated pairs of a key
(the name of the string) and a value (the contents of the string). The value can also be an array of strings, if required.

Initializing the database

errorcode = Open(

Open the library and lock for exclusive access by the calling plug-in. The calling plug-in is identified with the string plugin­name. It is recommended that this string equals the unique Sibelius menu name of the calling plug-in.

Parameter featureset is the version of the feature set requested by the calling plug-in. The version of the feature set is currently

020000. Each library release shows in its initial dialog a list of supported feature sets. The call to
a user message if you request an unsupported feature set. If you should want to prevent this user information (and probably
setup your own information dialog), use

After

Open()

pluginname,featureset

);

CheckFeatureSet()

Open()

first.

the scope is undefined, such that you can access only global variables until the first call to

will fail and show

SwitchScope()

.

Return value:

Open()

returns zero or a positive value on success. A negative result indicates that there was a fatal error and

the database has not been opened.

*

-2 other error

*

-1 library does not support requested feature set

*

0 no common preferences database found

*

1 no preferences found for current plug-in

*

2 preferences for current plug-in loaded

In case of errors (e.g. if the database file is unreadable),

Open()

offers the user an option to recover from the error condition.

Only if this fails too will an error code be returned to the calling plug-in.

errorcode = CheckFeatureSet(

featureset

);

Check silently if the library supports the requested feature set.

Return value:

CheckFeatureSet()

returns zero or a positive value on success. A negative value indicates that the

requested feature set is not supported by this version.

errorcode = Close();

Release the exclusive access lock to the library. If there were any changes since the last call to
data changes back to disk (probably creating a new score, if there was none present).

Return value:

Close()

returns zero or a positive value on success. A negative result indicates that there was a fatal error and

the database has not been written.

Open()

or

Write()

, dump the

errorcode = CloseWithoutWrite();

Release the exclusive access lock to the library, discarding any changes performed since last call to

Return value:

CloseWithoutWrite()

returns zero or a positive value on success. A negative result indicates that there

Open()

or

Write()

was a fatal error, namely that the database was not open at the moment.

errorcode = Write(

dirty

);

Force writing the data back to disk immediately. Keep library locked and open. If dirty equals 0, the write only takes place if the
data has been changed. If dirty is positive, the common preferences score is unconditionally forced to be rewritten from scratch.

Return value:

Write()

returns zero or a positive value on success. A negative result indicates that there was a fatal error and the

database has not been written.

30

.

Accessing data

index = SetKey(

Store a string value value under the name keyname in the database, overwriting any previously stored keys or arrays of the
same keyname.

If keyname has been declared as a local key, the key is stored within the current scope and does not affect similar keys in other
scopes. It is an error to call

keyname, value

SetKey()

);

for local keys if the scope is undefined.

Return value:

errorcode = SetArray(

SetKey()

returns zero or a positive value on success, and a negative value upon error.

keyname, array, size

);

Store a array array of strings under the name keyname in the database, overwriting any previously stored keys or arrays of the
same keyname. size specifies the number of elements in the array. A size of

array.NumChildren

i.e.,

.

-1

is replaced with the natural size of the array,

If keyname has been declared as a local key, the array is stored within the current scope and does not affect similar keys in
other scopes. It is an error to call

Return value:

value = GetKey(

SetArray()

keyname

SetArray()

returns zero or a positive value on success, and a negative value upon error.

);

Retrieve the value of key keyname from the database. It is an error to call
the last time using

SetArray()

Return value: The value of the key or

size = GetArray(

keyname, myarray

. For local keys, the value is retrieved from the current scope which must not be undefined.

Preferences.VOID

);

Retrieve the string array stored under name keyname from the database. It is an error to call
which has been stored the last time by

SetKey()

for local keys if the scope is undefined.

GetKey()

on an identifier which had been stored

if no key of that name found.

GetArray()

on an identifier

. For local arrays, the value is retrieved from the current scope which must

not be undefined.

You must ensure before the call that myarray is of ManuScript’s array type (i.e., created with

Return value: size equals the number of retrieved elements or

myarray.NumChildren

than

, because there is currently no way to reduce the size of an already defined array.

-1

if the array was not found. Note that size might be smaller

CreateArray()

).

size = GetListOfIds(

myarray

);

Fill the array myarray with a list of all known Ids in the current score (or in the global scope, if undefined). Before you call this
method, ensure that myarray is of ManuScript’s array type (i.e. created with

CreateArray()

Return value: returns the size of the list, which might be smaller than the natural size of the array,

.

dren

index = UnsetId(

keyname

);

).

myarray.Numchil-

Erase the contents stored with an identifier (there is no distinction between keys and arrays here). If the key is declared as
local, it is erased only from the local scope which must not be undefined.

Return value: The return value is zero or positive if the key has been unset. A negative return value means that a key of that
name has not been found (which is not an error condition).

RemoveId(

keyname

);

Erase all contents stored in the database with an identifier (there is no distinction between keys and arrays here). If the key is
declared as local, it is erased from all local scopes.

Return value: The return value is always zero.

RemoveAllIds();

Erase everything related to the current plug-in.

Return value: the return value is always zero.

Tutorial

Commands for local variables

errorcode = DeclareIdAsLocal(

keyname

);

Declare an identifier as a local key. Subsequent calls to
set at that time. The local state is stored in the database and can be undone by a call to

RemoveId

.

Set

... and

Get

... operations will be performed in the scope which is

DeclareIdAsGlobal

Return value: Non-negative on success, negative on error.

size = GetListOfLocalIds(

myarray

);

Fill the array myarray with a list of all Ids declared as local. Before you call this method, ensure that myarray is of ManuScript’s
array type (i.e. created with

CreateArray()

Return value: Returns the size of the list, which might be smaller than the natural size of the array,

.

dren

errorcode = SwitchScope(

scopename

).

myarray.NumChil-

);

Select scope scopename. If scope scopename has never been selected before, it is newly created and initialized with no local

Set

... and

Get

variables. Subsequent

... operations for keys declared as local will be performed in scope scopename, while

access to global keys is still possible.

The call

SwitchScope("")

selects the undefined scope which does not allow access of any local variables.

Return value: Non-negative on success, negative on error.

errorcode = RemoveScope();

Erase all local keys and arrays from the current scope and delete the current scope from the list of known scopes. It is an error

RemoveScope()

to call

if the current scope is undefined. After the call, the database remains in the undefined scope.

or

errorcode = RemoveAllScopes();

Erase all local keys and arrays from all scopes and delete all scopes from the list of known scopes. After the call, the database
remains in the undefined scope. Note that this call does retain the information which Ids are local (see

).

cal()

DeclareIdAsLo-

Return value: Non-negative on success.

string = GetCurrentScope();

Retrieve the name of the currently active scope, or the empty string if the database is in undefined scope.

Return value: Returns a string.

size = GetListOfScopes(

myarray

);

Fill the array myarray with a list of all known scope names. You must ensure before the call that myarray is of ManuScript’s
array type (i.e., created with

CreateArray()

Return value: Returns the size of the list, which might be smaller than the natural size of the array,

).

myarray.NumChildren

Miscellaneous

Trace(

TraceData();

tracelevel

);

Select level of tracing for the library. Useful levels are: 0 for no trace, 10 for sparse trace, 20 for medium trace, 30 for full trace.
This command can also be run when the library is not open, to specify the tracing level for the

Writes a full dump of the data stored currently in
current plug-in.

TraceData()

always traces the data, regardless of the current trace level selected.

ThisData

array to the trace window. This is the full data belonging to the

Open()

call itself.

.

filename = GetFilename();

Return the full filename of the preferences database (including path).

Editor();

32

Invoke the interactive plug-in editor. This method must not be called while the database is open. Direct calls to

Editor()

from plug-ins are deprecated, since the end-user of your plug-in will probably not expect to be able to edit (and destroy) the
saved preferences of all plug-ins at this stage.

Basic example

Suppose you have a plug-in called myplugin and would like to save some dialog settings in a preferences file such that these
settings are persistent over several Sibelius sessions and computer reboots. Your dialog may contain two checkboxes and a list box.
Let

DialogDontAskAgain

respectively, and let

DialogJobList

The work with the database can be reduced to four steps:

and

DialogSpeedMode

hold the contents of the list box item.

be the global variables holding the status of the checkboxes,

1. Open the database and retrieve initial data. At begin of your plug-in, e.g. right at top of your

Run()

method, you have to add
some code to initialize the database. You probably also want to initialize your global keys based on the information currently
stored in the database. See below for a detailed example. (Depending on your program, you might have to define

prefOpen

as a

global variable in order to prevent trying to access an unopened database in future.)

// At first define hard coded plug-in defaults, in case that the plug-in
// is called for the first time. If anything else fails, these defaults
// will be in effect.

DialogDontAskAgain = 0;
DialogSpeedMode = 0;
DialogJobList = CreateArray();
DialogJobList[0] = "first job";
DialogJobList[1] = "second job";

// Attempt to open the database

prefOpen = Preferences.Open( "myplugin", "020000" );
if( prefOpen >= 0 ) {

// Database successfully opened. So we can try to load the
// information stored last time.
// It’s a good idea to work with a private version scheme, in order
// to avoid problems in the future when the plug-in is developed
// further, but the database still contains the old keys. In our
// example, we propose that the above mentioned keys are present
// if "version" key is present and has a value of "1".

version = Preferences.GetKey( "Version" );

switch( version ) {

case( "1" ) {

// Now overwrite the above set defaults with the information stored
// in the database.

DialogDontAskAgain = Preferences.Getkey( "DontAskAgain" );
DialogSpeedMode = Preferences.Getkey( "SpeedMode" );
Preferences.GetArray( "JobList", DialogJobList );

}

default {

// handle other versions/unset version gracefully here ...

}

}

}

Tutorial

2. Work with the data. After the initialization step, you can and should work with global variables

DialogSpeedMode

, and

DialogJobList

as you are used to: read from them to base control flow decisions on their setting,

DialogDontAskAgain

write to them (mostly from within your own dialogs) to set new user preferences.

3. Write data back to the database. To make any changes persistent, you must tell the database the new values to be written to the
hard disk. See below for a detailed example. According to taste, you can execute these lines each time the settings are changed, or
only once, at the end of your plug-in.

if( prefOpen >= 0 ) {

Preferences.SetKey( "Version", "1" );
Preferences.SetKey( "DontAskAgain", DialogDontAskAgain );
Preferences.SetKey( "SpeedMode", DialogSpeedMode );
Preferences.SetArray( "JobList", DialogJobList, -1 );

}

4. Close the database. In any case, you must release the lock to the library on exit of your plug-in. This writes data actually back to
disk, and enables other plug-ins to access the shared database later. To do this, use:

Preferences.Close();

,

34

Storing and retrieving preferences

Reference

35

Reference

Syntax

Here is an informal run-down of the syntax of ManuScript.

A method consists of a list of statements of the following kinds:

{

Block

While

Switch

statements

e.g.

while {

e.g.

switch (
case (

case (

[

…

[

default

}

{

a = 4;

}

expression } block

while (i < 3) {

Sibelius.MessageBox(i);
i = i + 1;

}

test-expression

case-expression-1) block

case-expression-2) block ]

block ]

) {

if else

The switch statement consists of a “test” expression, multiple case statements and an
optional default statement. If the value of test-expression matches one of the case-expres­sions, then the statement block following the matching case statement will be executed. If
none of the case statements match, then the statement block following the default state­ment will be executed. For example:

switch (note.Accidental) {

case (DoubleSharp) {

Sibelius.MessageBox("Double sharp");
}
case (DoubleFlat) {

Sibelius.MessageBox("Double flat");
}
default {

Sibelius.MessageBox("No double");
}

}

if (

expression) block [

else

block ]

e.g.

if (found) {

Application.ShowFindResults(found);

} else {

Application.NotFindResults();

}

36

Syntax

for each

for

for each

variable in expression

block

This sets variable to each of the sub-objects within the object given by the expression.

Normally there is only one type of sub-object that the object can contain. For instance, a
NoteRest (such as a chord) can only contain Note objects. However, if more than one type of
sub-object is possible you can specify the type:

for each

Type var iable in expression

block

e.g.

for each NoteRest n in thisstaff {

n.AddNote(60); // add middle C

}

for

variable = value to value [

step

value ]

block

The variable is stepped from the first value up to or down to the end value by the step value.
It stops one step before the final value.

So, for example:

for x=1 to note.NoteCount {

...

}

works correctly.

assignment variable

=

expression

;

e.g.

=

value

value

+ 1;

or

variable

variable = expression

;

.

e.g.

Question.CurrentAnswer=True;

method call variable.identifier(comma-separated expressions

e.g.

thisbar.AddText(0,"Mozart","text.system.composer");

self method call identifier(comma-separated expressions

);

Calls a method in this plug-in, e.g.

CheckIntervals();

return

return

expression

;

Returns a value from a plug-in method, given by the expression. If a method doesn’t con­tain a

return

string, or the

statement, then a “null” value is returned (either the number zero, an empty

null

object described below).

);

37

Reference

Expressions

Here are the operators, literals and other beasts you’re allowed in expressions.

Self This is a keyword referring to the plug-in owning the method. You can pass yourself to

other methods,

null This is a literal object meaning “nothing.”

Identifier This is the name of a variable or method (letters, digits or underscore, not starting with a

digit) you can precede the identifier with
taken to be a string variable whose value is used as the name of a variable or method.

member variable variable

.

This accesses a variable in another object.

integer e.g.

floating point number e.g.

1, 100, -1

1.5, 3.15, -1.8

string Text in double quotes, e.g.

of the score, i.e. the contents of some text object, there is a small but useful formatting lan­guage allowing one to specify how the text should appear. These “styled strings” contain
commands to control the text style. All commands start and end with a backslash (
full list of available styling commands is as follows:

e.g.

other.Introduce(Self);

variable

"some text"

@

to provide indirection; the identifier is then

. For strings that are rendered by Sibelius as part

\

) The

\n\

\N\

\B\

\b\

\I\

\i\

\U\

\u\

\fArial Black\

\ctext.character.musictext\

New paragraph

New line

Bold on

Bold off

Italic on

Italic off

Underline on

Underline off

Font change to Arial Black (for example)

Character style change to Music text (for example)

\f_\

Font change to text style’s default font, including removing any active
character styles

\s123\

\v\

\h\

\t\

\p\

Size change to 123 (units are 1/32nds of a space, not points)

Vertical scale in percent

Horizontal scale in percent

Tracking (absolute) in 1/32nds of a space

Baseline adjustment: use
(for superscript)

\$

keyword

\

Substitutes a string from the Score Info dialog (see below)

normal, sub

(for subscript) or

super

38

A consequence of this syntax is that backslashes themselves are represented by
conflicting with the above commands.

\$

The substitution command

poser

,

Arranger, Lyricist, MoreInfo, Artist, Copyright, Publisher

PartName

. Each of these correspond to a field in the File> Score Info dialog

keyword\ supports the following keywords:

Title, Com-

\\

, to avoid

.

and

not

not

expression

Logically negates an expression, e.g.

not (x=0)

and expression

and

expression

Logical and, e.g.

FoxFound and BadgerFound

or expression or expression

Logical or, e.g.

FoxFound or BadgerFound

equality expression = expression

Equality test, e.g.

Name="Clock"

subtract expression – expression

Subtraction, e.g.

12-1

add expression + expression

Addition, e.g.

12+1

minus

–

expression

Inversion, e.g.

-1

concatenation expression & expression

Add two strings, e.g.

Name = "Fred" & "Bloggs"; // ‘Fred Bloggs’

You can’t use + as this would attempt to add two numbers, and sometimes succeed (!). For
instance:

x = "2" + "2"; // same as x = 4

subexpression

(

expression

)

For grouping expressions and enforcing precedence, e.g.

(4+1)*5

method call

variable.identifier(

comma-separated expressions

e.g.

x = monkey.CountBananas();

self method call Identifier(comma-separated expressions

Calls a method in this plug-in, e.g.

x = CountBananas();

);

);

Reference

Operators

Condition operators

You can put any expressions in parentheses after an if or
and <. The available conditions are very simple:

while

statement, but typically they will contain conditions such as

=

a = b

a < b

a > b

c and d

c or d

not c

<=

>=

!=

Note that you use

Arithmetic

a + b

a - b

a * b

a / b

a % b

equals (for numbers, text or objects)

less than (for numbers)

greater than (for numbers)

both are true

either are true

inverts a condition, e.g.

not(x=4)

less than or equal to

greater than or equal to

not equal to

=

to compare for equality, not == as found in C/C++ and Java.

add

subtract

multiply

divide

remainder

-a

(a)

ManuScript will evaluate expressions from left to right, so that

negate

evaluate first

2+3*4

is 20, not 14 as you might expect. To avoid problems with

evaluation order, use parentheses to make the order of evaluation explicit. To get the answer 14, you’d have to write

ManuScript also now supports floating point numbers, so whereas in previous versions
to 1.5. Conversion from floating point numbers to integers is achieved with the

Round(

expr)functions, which can be applied to any expression.

3/2

would work out as 1, it now evaluates

RoundUp(

expr),

RoundDown(

2+(3*4)

expr) and

.

40

Operators

Object Reference

41

Object Reference

Sibelius object

Score

Stave (including the SystemStave)Selection

Bar

Text, Clef, Line, TimeSignature, KeySignature,
Highlight, Lyric, Barline, Tuplet, GuitarFrame,

GuitarScaleDiagram, Comment,

NoteRest (these are all BarObjects)

Note (in NoteRests only)

VersionHistory

Ve rs io n

VersionComment

DynamicPartCollection

DynamicPart

EngravingRules

NoteSpacingRule

Hierarchy of objects

42

All objects

Methods

AddToPluginsMenu("

Adds a new menu item to the Plug-ins menu. When the menu item is selected the given function is called. This is normally
only used by plug-ins themselves. This method may only be called once per plug-in (i.e. each plug-in may only add one item
to the Plug-ins menu); subsequent method calls will be ignored.

Asc(

expression

)

Returns the ASCII value of a given character (the expression should be a string of length 1).

menu text

","

function name

")

All objects

CharAt(

Chr(

expression,position

)

Returns the character from the expression at the given (zero-based) position, e.g.

expression

)

CharAt("Potato",3)

would give “a.”

Returns a character (as a string) with the given ASCII value. This can be used for inserting double quotes (") into strings with

Chr(34)

CreateArray()

.

Returns a new array object.

CreateHash()

Returns a new hash-table object.

GetValidationError(

object

)

Returns the validation error, if any, of the specified object. Useful to pass validation errors to the plug-in trace window.

ExitPlugin()

Exits the plug-in cleanly without dropping into the plug-in editor

IsObject(

Returns 1 (or

(Not to be confused with the

IsValid(

Returns 1 (or

expression

True

object

)

True

)

) if expression evaluates to an object rather than a null, boolean, string, or any number.

IsPassage

) if the object is valid, returns 0 (or

variable of Selection objects!)

False

) if the object no longer exists (i.e. has been deleted).

JoinStrings(

expression, delimiter

)

Joins together (concatenates) an array of strings into a single string, separated by the string delimiter.

Length(

expression

)

Gives the number of characters in the value of the expression.

Round(

RoundDown(

RoundUp(

SplitString(

expression

Returns the nearest integer to the value of the expression, e.g.

Returns the nearest integer less than the value of the expression, e.g.

)

expression

expression

Round(1.5)

)

RoundDown(1.5)

)

Returns the nearest integer greater than the value of the expression, e.g.

expression,[delimiter,][trimEmpty]

)

would be “2” and

RoundUp(1.5)

Round(1.3)

would be “1.”

would be “2.”

would be “1.”

Splits a string into an array of strings, using the given delimiter. The delimiter can be a single character or a string containing

".,"

several characters – for instance

would treat either a comma or full stop as a delimiter. The default delimiter is the space

43

Object Reference

character. If the trimEmpty parameter is

True

empty strings in the array). The default value of trimEmpty is

s=':a:b:c';
bits=SplitString(s,':', false);
// bits[0] = ''; bits[1] = 'a'; bits[2] = 'b' ...
s='a b c';
bits=SplitString(s,' ', true);
// bits[0] = 'a'; bits[1]='b' ...

then this will ignore multiple delimiters (which would otherwise produce some

False

.

StopPlugin(

[message]

)

Stops the plug-in, and shows the optional message in an alert box. Opens the plug-in editor at the line of code reached.

Substring(

expression,start,[length]

)

This returns a substring of the expression starting from the given start position (zero-based) up to the end of the expression,

Substring("Potato",2)

e.g.

would give “tato”. When used with the optional length parameter, Substring returns a sub-

string of the of the expression starting from the given start position (zero-based) of the given length, e.g.

string("Potato",2,2)

Trace(

expression

)

Sends a piece of text to be shown in the plug-in trace window, e.g.

ValidationChecking(

would give “ta”.

Trace("Here's a trace");

enable[, object1[, object2]...])

If enable is the only parameter, validation checking is enabled for all types of objects, and across all plug-ins. If you supply one
or more object parameters (e.g.

Tuplet, Score, BarObject

rently running plug-in. You should ensure

ValidationChecking

, etc.), only those objects will be checked, and only in the cur-

is set to

false

before you give your plug-ins to any-

body else to use.

User properties

All objects (except for the
hashes created using
page 22 for more details.

Sibelius

CreateHash()

object, old-style ManuScript arrays created using

, and

null

) can also have user properties assigned to them. See

CreateArray()

, old-style ManuScript

User properties

Sub-

on

44

Accessibility

Accessed from the Sibelius object.

Methods

None.

Varia bles

ScoreDescription

Returns

true

if Sibelius’s built-in score description functionality is enabled (read/write).

Accessibility

45

Object Reference

Bar

A Bar contains BarObject objects.

for each

for each

variable in produces the BarObjects in the bar

type variable in produces the BarObjects of the specified type in the bar

Methods

AddBarNumber(

Adds a bar number change to the start of this bar. new bar number should be the desired external bar number. The optional
format parameter takes one of the three pre-defined constants that define the bar number format; see

page 139. The optional extra_text parameter takes a string that will be added after the numeric part of the bar number, unless
the optional boolean parameter prepend is
number. If the optional skip this bar parameter is
number option set. Returns the BarNumber object created.

AddChordSymbolFromPitches(

Adds a chord symbol from the given array of pitches at the specified position. The optional instrument style parameter oper­ates the same as in the
returns null; otherwise it returns the GuitarFrame object created.

AddClef(

Adds a clef to the staff at the specified position. concert pitch clef determines the clef style when Notes> Transposing
Score is switched off; the optional transposed pitch clef parameter determines the clef style when this is switched on. Clef

styles should be an identifier like “clef.treble”; for a complete list of available clef styles, see
tively you can give the name of a clef style, e.g. “Treble,” but bear in mind that this may not work in non-English versions of
Sibelius. Returns the Clef object created.

new bar number[,format[,extra_text[,prepend[,skip this bar]]]]

True

, in which case the extra_text is added before the numeric part of the bar

True

, the bar number change is created with the Don’t increment bar

position,pitches[,instrument style]

AddGuitarFrame

pos,concert pitch clef[,transposed pitch clef]

method (see above). If the method is unable to create a chord symbol, the method

)

)

Global constants

)

Clef styles

on page 143. Alterna-

on

AddComment(sr,

text[,color[,maximized]]

)

Adds a comment at the specified sr position in the current bar, displaying the specified text. The optional color parameter
allows you to specify the color of the comment that is created (if not specified, the comment is created with its default color),
and the optional maximized Boolean parameter allows you to set the comment to be minimized (if not specified, the comment
is created maximized by default). If you want to specify the maximized parameter without specifying a particular color, set

-1

color to

AddCommentWithName(sr,

.

text,username[,color[,maximized]]

)

Adds a comment that will display a given username at the specified sr position in the current bar, displaying the specified text.
The optional color parameter allows you to specify the color of the comment that is created (if not specified, the comment is
created with its default color), and the optional maximized Boolean parameter allows you to set the comment to be minimized
(if not specified, the comment is created maximized by default). If you want to specify the maximized parameter without spec-

-1

ifying a particular color, set color to

AddGraphic(

file name,pos[,below staff[,x displacement[,y displacement[,size ratio]]]]

.

)

Adds a graphic above or below the bar at a given position. If below staff is True, Sibelius will position the graphic below the
staff to which it is attached, otherwise it will go above (the default). You may additionally displace the graphic from its default
position by specifying x- and y displacements. These should be expressed in millimeters, the latter defining an offset from the
top or bottom line of the staff, as appropriate. By default, the graphic will be created 5mm away from the staff. To adjust the
size of the graphic, you may set a floating point number for its size ratio. When set to 1.0 (the default), the graphic will be cre­ated with a height equal to that of the staff to which it is attached. A value of 0.5 would therefore halve its size, and 2.0 double
it. The graphic may be rescaled to a maximum of five times the height of its parent staff. This function returns Tru e if success­ful, otherwise False.

46

Bar

AddGraphicToBlankPage(

file name,nth page,x offset,y offset[,size ratio]

)

Adds a graphic to a blank page belonging to the current bar. nth page specifies the particular blank page you would like the
graphic to, starting from 1. The x offset and y offset parameters are floating point values relative to the size of the page the
graphic is being added to. For example, an x offset of 0.0 would position the graphic at the very left of the page; 0.5 in the cen­tre. You may specify the size of the graphic by specifying a value for size ratio. This defaults to 1.0, which has the same effect
as creating a graphic in Sibelius manually using Create

Graphic. (As with

AddGraphic

, 0.5 would halve its size, and

>

2.0 double it.) The graphic may be rescaled to a maximum of five times its intial size. This function returns Tr ue if successful,
otherwise False.

AddGuitarFrame(

position,chord name[,instrument style[,fingerings]

)

Adds a chord symbol for the given chord name to the bar. The optional instrument style parameter should refer to an existing
instrument type that uses tab, and should be specified by identifier; see

Instrument types

on page 143. If instrument style

is not specified, Sibelius will create a chord symbol that will optionally display a chord diagram using the default tab tuning
associated with the instrument type used by the staff to which the chord symbol will be attached. The position is in 1/256th
quarters from the start of the bar. The optional fingerings parameter gives the fingerings string to display above (or below) the
guitar frame, if supplied. If the method is unable to create a chord symbol, the method returns null; otherwise it returns the
GuitarFrame object created.

AddInstrumentChange(

[full_instrument_name[, short_instrument_name]]]]]]

pos,styleID[,add_clef[,show_text[,text_label[,show_warning[,warning_label

)

,

Adds an instrument change to the bar at the specified position. styleID is the string representing the instrument type to
change to (see

Instrument types

on page 143 for a list). The optional boolean parameter add_clef,

True

if not specified,

determines whether Sibelius will add a clef change at the same position as the instrument change if required (i.e. if the clef of
the new instrument is different to that of the existing instrument). show_text is an optional boolean parameter,

True

specified, determining whether or not the text label attached to the instrument change should be created shown (the default)
or hidden. text_label is an optional string parameter; if specified, Sibelius will use this string instead of the default string (the

True

new instrument’s long name). show_warning is an optional boolean parameter,

if not specified, determining whether or

not Sibelius should create a text object (using the Instrument change staff text style) above the last note preceding the instru­ment change, announcing the instrument change and giving the player time to pick up the new instrument. warning_label is
an optional string parameter; if specified, Sibelius will use this string instead of the default string (the word “To” followed by
the new instrument’s short name). You can also override the names Sibelius will give the instruments on subsequent systems.
If a null string is passed to either full_instrument_name or short_instrument_name (or if the arguments are omited), the
instrument names will remain unchanged. Returns the InstrumentChange object created.

if not

AddKeySignatureFromText(

pos,key name,major key[,add double barline[,hidden[,one staff only]]]

)

Adds a key signature to the bar. The key signature is specified by text name, e.g. “Cb” or “C#”. The third parameter is a Boolean

False

flag indicating if the key is major (or minor). Unless the fourth parameter is set to

, a double barline will ordinarily be

created alongside the key signature change. You may additionally hide the key signature change by setting hidden to
and make the change of key appear on the bar’s parent staff only with the one staff only flag. Returns the key signature object
created.

AddKeySignature(

pos,num sharps,major key[,add double barline[,hidden[,one staff only]]]

)

Adds a key signature to the bar. The key signature is specified by number of sharps (+1 to +7), flats (-1 to –7), no accidentals
(0) or atonal (-8). The third parameter is a Boolean flag indicating if the key is major (or minor). Unless the fourth parameter

False

is set to
key signature change by setting hidden to

, a double barline will ordinarily be created alongside the key signature change. You may additionally hide the

True

, and make the change of key appear on the bar’s parent staff only with the one

staff only flag. Returns the key signature object created.

AddLine(

pos,duration,line style[,dx[,dy[,voicenumber[,hidden]]]]

)

Adds a line to the bar. The line style can be an identifier such as “line.staff.hairpin.crescendo” or a name, e.g. “Crescendo”. For
a complete list of line style identifiers that can be used in any Sibelius score, see

Line styles

on page 142. Style identifiers are
to be preferred to named line styles as they will work across all language versions of Sibelius. Returns the Line object created,
which may be one of a number of types depending on the Line style used.

True

,

47

Object Reference

AddLiveTempoTapPoint(

position

)

Adds a Live Tempo tap point at the rhythmic position specified by position, in 1/256th quarters from the start of the bar.

AddLyric(

position,duration,text[,syllable type [,number of notes,voicenum]]]

)

This method adds a lyric to the bar. The position is in 1/256th quarters from the start of the bar, and the duration is in 1/256th
quarter units. The two optional parameters allow you to specify whether the lyric is at the end of a word (value is “1”, and is the
normal value) or at the start or middle of a word (value is “0”), and how many notes the lyric extends beneath (default value

1). You can also optionally specify the voice in which the lyric should be created; if voicenum is 0 or not specified, the lyric is
created in all voices. Returns the LyricItem object created.

AddNote(

pos,sounding pitch,duration,[tied [,voice[,diatonic pitch[,string number]]]]

)

Adds a note to staff, adding to an existing NoteRest if already at this position (in which case the duration is ignored); other­wise creates a new NoteRest. Will add a new bar if necessary at the end of the staff. The position is in 1/256th quarters from

True

the start of the bar. The optional tied parameter should be

if you want the note to be tied. Voice 1 is assumed unless the
optional voice parameter (with a value of 1, 2, 3 or 4) is specified. You can also set the diatonic pitch, i.e. the number of the
“note name” to which this note corresponds, 7 per octave (35 = middle C, 36 = D, 37 = E and so on). If a diatonic pitch of zero
is given, a suitable diatonic pitch will be calculated from the MIDI pitch. The optional string number parameter gives a string
number for this note, which is only meaningful if the note is on a tablature stave. If this parameter is not supplied then a
default string number is calculated based on the current tablature stave type and the guitar tab fingering options (specified on

>

the Notes page of File

Note.ParentNoteRest

AddPageNumber(

[blank page offset]

Preferences). Returns the Note object created (to get the NoteRest containing the note, use

).

)

Creates and returns a page number change at the end of the bar. Note that – due to the nature of adding a page number change
– a page break will also be created at the end of the bar. Therefore, the page number change will actually be placed at the start
of the next bar. The desired properties of the page number change can be set by calling the appropriate methods on the Page
Number Change object returned.

The blank page offset flag allows you to create page number changes on blank pages. If a bar object is followed by one or more
blank pages, each blank page may also have a page number change of its own. If unspecified, the page number change will be
created on the next available page (whether it contains music or not) after the bar, otherwise the user may specify a 1-based
offset which refers to the nth blank page after the bar itself.

AddPageNumberAtStartOfBar()

Creates and returns a page number change at the start of the bar. This is useful for adding a page number change at the very
start of the score, i.e. to change the initial page number, by using this method on the first bar of the score. If used on a bar later
in the score, it will create the page number change at the end of the previous bar, but unlike the
will not force a page break, so in general the

AddRehearsalMark(

[consecutive[,mark[,new prefix and suffix[,prefix[,suffx[,override defaults]]]]]

AddPageNumber

method is recommended.

AddPageNumber

)

method, it

Adds a rehearsal mark above the bar. If no parameters have been specified, the rehearsal mark will inherit the properties of the
previous rehearsal mark in the score, incrementing accordingly. Optionally, the appearance of the rehearsal mark may be
overriden. If consecutive is False, Sibelius will not continue the numbering of the new rehearsal marks consecutively, but
allow the user to set a new mark. A mark may be expressed as a number of a string. For example both 5 and “e” are both valid
and equivalent values. If new prefix and suffix is Tru e, the values set for prefix and suffix will be applied to the new rehearsal
mark. The final parameter, override defaults, is a Boolean defaulting to False whose purpose it is to mimic the behavior of the
option with the same name in the Rehearsal Mark dialog in Sibelius.

AddSpecialBarline(

Adds a special barline to a given position in a bar; see

barline type[,pos]

)

Global constants

on page 139. If no position has been specified,

start repeat barlines will snap to the start of the bar by default. All other special barline types will snap to the end.

AddSymbol(

pos,symbol index or name

)

Adds a symbol to the bar at the specified position. If the second parameter is a number, this is taken to be an index into the

>

global list of symbols, corresponding to the symbol’s position in the Create

Symbol dialog in Sibelius (counting left-to-

48

Bar

right, top-to-bottom from zero in the top-left hand corner). Some useful symbols have pre-defined constants; see

constants

to access the 8va symbol, for example, you can use the index

on page 139. There are also constants defined for the start of each group in the Create> Symbol dialog, so that

OctaveSymbols + 2

. It’s better to use indices rather than

names, because the names will be different across the various language versions of Sibelius. Returns the Symbol object

null

created, or

AddText(

pos,text,style[,voicenum]

if no symbol can be added to the score.

)

Adds the text at the given position, using the given text style. A staff text style must be used for a normal staff, and a system
text style for a system staff. The styles should be an identifier of the form “text.staff.expression”; for a complete list of text
styles present in all scores, see

Text styles

on page 141. Alternatively you can give the name of a text style, eg. “Expression”,

but be aware that this may not work in non-English versions of Sibelius. You can also optionally specify the voice in which the
lyric should be created; if voicenum is 0 or not specified, the text object is created in all voices. Returns the Text object created.

AddTextToBlankPage(

xPos,yPos,text,style,pageOffset

)

Adds the text at the given position, using the given text style. A blank page text style must be used; you cannot add staff text or
system text to a blank page. style takes a style ID, using the form “text.blankpage.title”; for a complete list of text styles present
in all scores, see

Text styles

number for a blank page following a special page break (the first blank page is
first bar of the score (the blank page immediately before the first bar is

on page 141. xPos and yPos are the absolute position on the page. pageOffset takes a positive

1

), and negative for a blank page preceding the

-1

, the one before that -2, and so on). Returns the

Text object created.

To add text to a blank page, first create the special page break using the
blank pages using

Bar.NumBlankPages

or

Bar.NumBlankPagesBefore

Bar.BreakType

. Then use

variable, and set the number of

Bar.AddTextToBlankPage

Global

.

AddTimeSignature(

top,bottom,allow cautionary,rewrite music[,use symbol]

)

Returns an error string (which will be empty if there was no error) which if not empty should be shown to the user. The first
two parameters are the top and bottom of the new time signature. The third tells Sibelius whether to display cautionary time
signatures from this time signature. If rewrite music is

True

then all the bars after the inserted the time signature will be

rewritten. You can also create common time and alla breve time signatures. If you’re creating a time signature in 4/4 or 2/2, set
use symbol to True and Sibelius will replace the numbers of the time signature with their symbolic equivalent.

AddTimeSignatureReturnObject(

top,bottom,allow cautionary,rewrite music[,use symbol]

)

As above, but returns the time signature object created, or null if unsuccessful.

AddTuplet(

pos,voice,left, right, unit[, style[, bracket[, fullDuration]]]

)

Adds a tuplet to a bar at a given position. The left and right parameters specify the ratio of the tuplet, e.g. 3 (left) in the time of
2 (right). The unit parameter specifies the note value (in 1/256th quarters) on which the tuplet should be based. For example,
if you wish to create an eighth note (quaver) triplet group, you would use the value 128. The optional style and bracket param­eters take one of the pre-defined constants that affect the visual appearance of the created tuplet; see

Global constants

page 139. If fullDuration is true, the bracket of the tuplet will span the entire duration of the tuplet. Returns the Tuplet object
created.

N.B.: If

AddTuplet()

has been given illegal parameters, it will not be able to create a valid Tuplet object. Therefore, you

should test for inequality of the returned Tuplet object with null before attempting to use it.

Bar[

array element

Returns the nth item in the bar (counting from 0) e.g.

]

Bar[0]

on

Clear(

[voice number]

)

Clears a bar of all its items, leaving only a bar rest. If a particular voice number is specified, only the items in that voice will be
removed.

ClearNotesAndModifiers(

[voice number]

)

Clears a bar of all its notes, rests, tuplets and slurs, replacing them with a single bar rest. If a particular voice number is speci­fied, only the items in that voice will be removed.

49

Object Reference

Delete()

Deletes and removes an entire bar from a score. This, by definition, will affect all the staves in the score.

DeletePageNumber(

[blank page offset]

)

Deletes the page number change at the end of the bar, or if there are one or more blank pages after the bar, any page number
change that occurs on any of those blank pages. If blank page offset is unspecified, the page number change on the first page
after the bar will be deleted.

GetClefAt(

pos

)

Returns a Clef object corresponding to the current clef at the specified rhythmic position.

GetKeySignatureAt(

pos

)

Returns a KeySignature object corresponding to the current clef at the specified rhythmic position.

GetInstrumentTypeAt(

pos

)

Returns an InstrumentType object representing the instrument type used by the bar at the specified rhythmic position.

GetPageNumber(

[blank page offset]

)

Returns the page number change object at the end of the bar, or if the bar contains no page number change, null. As with

AddPageNumber

, you may get the page number change from any of the blank pages that follow the bar by specifying a valid

blank page offset.

InsertBarRest(

voice number[,rest type]

)

Inserts a bar rest into the bar, but only if the bar is void of any NoteRests (or an existing bar rest) using the same voice
number.The optional rest type parameter allows you to specify the type of bar rest or repeat bar to be created, defined by the

constants
and

WholeBarRest

FourBarRepeat

(the default if rest type is not specified),

. Returns True if successful.

BreveBarRest, OneBarRepeat, TwoBarRepeat

NthBarObject(n)

Returns the nth object in the bar, counting from 0.

RemoveLiveTempoTapPoint(

position

)

Removes a Live Tempo tap point at the rhythmic position specified by position, in 1/256th quarters from the start of the bar.

ResetSpaceAroundBar(

above,below

)

Does the equivalent of Layout> Reset Space Above Staff and/or Reset Space Below Staff for the given bar. Set
above to

Respace()

True

to reset the space above the staff, and below to

True

to reset the space below the staff.

Respaces the notes in this bar.

Varia bles

BarNumber

BarObjectCount

BreakType

The bar number of this bar. This is the internal bar number, which always runs consecutively
from 1 (read only).

The number of objects in the bar (read only).

The break at the end of this bar, given by the constants

MiddleOfPage, EndOfPage, NotEndOfSystem, EndOfSystemOrPage
SpecialPageBreak

. To learn the correspondence between these constants and the menu

in the Bars panel of the Properties window, see the discussion in

MiddleOfSystem, EndOfSystem

Global constants

page 139.

,

or

on

50

When you set the break at the end of a bar to be

SpecialPageBreak

, Sibelius will add one

blank page after the break. You can then adjust the number of pages by setting the value of

Bar.NumBlankPages

either
the music on the next left or right page with

or

Bar.NumBlankPagesBefore

Bar.MusicRestartsOnPage

, or tell Sibelius to restart

.

Bar

ExternalBarNumber

ExternalBarNumberString

GapAfter

GapBefore

InMultirest

Length

MusicRestartsOnPage

This has been deprecated as of Sibelius 5, because it can only return a number, and bar num­bers that appear in the score may now include text. Use

ExternalBarNumberString

instead.

Returns the external bar number of this bar, taking into account bar number changes in the
score (read only). Note that you cannot pass this bar number to any of the other ManuScript
accessors; they all operate with the internal bar number instead.

The external bar number of this bar as a string, taking into account bar number changes and
bar number format changes (read only). Note that you cannot pass this bar number to any of
the other ManuScript accessors; they all operate with the internal bar number instead.

Sets the gap (in spaces) after the bar (read/write)

Sets the gap (in spaces) before the bar (read/write).

Returns one of four global constants describing if and/or where the bar falls in a
multirest (read only). The constants are NoMultirest, StartsMultirest, EndsMultirest
and MidMultirest; see

Global constants

on page 139.

The rhythmic length (read only).

Tells Sibelius to restart the music on the next left or right page after a special page break, and
can only be set if

BreakType

of the global special page break constants:

MusicRestartsOnNextRightPage

is

SpecialPageBreak

(write only).

. This variable may be set to only two

MusicRestartsOnNextLeftPage

or

NthBarInSystem

NumBlankPages

NumBlankPagesBefore

OnHiddenStave

OnNthPage

OnNthPageExternal

OnNthSystem

ParentStaff

SectionEnd

Selected

SpecialPageBreakType

SplitMultirest

Time

Returns the position of the bar in the system, relative to the first bar on the system (bar 0) (read
only).

The number of blank pages following the bar containing a special page break.

The number of blank pages preceding the bar containing a special page break. This value only
has an effect if a special page break exists in bar 1.

Returns True if the bar is currently hidden by way of Hide Empty Staves (read only).

Returns the zero-based page number on which the bar occurs in the current part (read only).

Returns a string containing the external page number (i.e. the page number displayed in the
score) of the page in which the bar occurs.

Returns the zero-based system number (relative to its parent page) in which the bar occurs
(read only).

The staff containing this bar (read only).

Corresponds to the Section end checkbox on the Bars panel of Properties (read/write).

Returns True if the entire bar is currently selected (read only).

Returns the type of the special page break; see the documentation for the Special page break
types in

When

Global constants

True

, a multirest intersecting the bar in question will be split (read/write).

on page 139 (read only).

The time at which the bar starts in the score in milliseconds (read only).

51

Object Reference

Barline

Accessed from a Barlines object.

Methods

None.

Varia bles

BottomStave

Returns the Staff object at which the barline ends, relative to the current part.

BottomStaveNum

TopStave

TopStaveNum

Returns the number of the bottom staff included in the barline, relative to the current part.

Returns the Staff object at which the barline starts, relative to the current part.

Returns the number of the top staff included in the barline, relative to the current part.

52

Barlines

Accessed from a Score object. Corresponds to the barline groupings in the score.

Barlines

for each

s = Sibelius.ActiveScore;
barlines = s.Barlines;
for each barline in barlines {
// do something with barlines here
}

Array access [int n] returns the nth barline in the list, or null if the barline does not exist.

barline in iterates through all the barlines in the list, e.g.

Methods

AddBarline(

Creates a new bar line inclusively spanning the staff numbers (relative to the current part) supplied. Returns the new Barline
object created, or null if it fails.

ClearAll()

Removes all the barlines from the score.

DeleteNthBarline(

Removes a given barline identified by index from the score.

top staff number, bottom staff number

index

)

)

Varia bles

NumChildren

Returns the number of unique barlines in the score (read only).

53

Object Reference

BarObject

BarObjects include Clef, Line, NoteRest & Text objects. All the methods and variables below apply to all specific types of
BarObject – they are listed here instead of separately for each type. (To object-oriented programmers, the NoteRest, Clef etc. types
are derived from the base class BarObject.)

Methods

Delete()

Deletes an item from the score. This will completely remove text objects, clefs, lines etc. from the score; however, when
a NoteRest is deleted, it will be converted into a rest of similar duration. To delete multiple items from a bar, see

multiple objects from a bar

Deselect()

below.

Removes the object from the selection list of the parent score. If the selection is currently a passage selection, it is first changed

True

to a multiple selection before the object is deselected. Returns

FreezeMagneticLayoutPositions()

if the object is successfully removed from the selection.

Does the same as selecting an object and choosing Layout> Freeze Magnetic Layout Positions, i.e. explicitly sets the

Dx/Dy

object’s

to the position produced by Magnetic Layout, then disables Magnetic Layout for that object.

Deleting

GetIsInVoice(

Returns

GetPlayedOnNthPass(n)

Returns

NextItem(

voicenum

True

if the object is in the voicenum specified.

True

if the object is set to play back the nth time.

[voice[, item type]]

)

)

Returns the next item in the parent bar of the current item, or null if no item exists. If no arguments have been supplied, the
very next item in the bar will be returned, regardless of its voice number and item type. You may additionally specify the voice
number of the object you’re looking for (1 to 4, or 0 for any voice number), and the item’s type. Note that an item will only be
returned if it exists in the same bar as the source item. By way of example, to find the next crescendo line in voice 2, you would
type something along the lines of:

PreviousItem(

[voice[, item type]]

hairpin = item.NextItem(2, “CrescendoLine”);

)

As above, but searches backwards.

RemoveVoice(

voicenum

)

Removes the object from the specified voicenum, leaving the object in all remaining voices.

ResetPosition(

[horizontal[, vertical]]

)

Performs Layout> Reset Position on the object. If you supply no parameters, this method will reset both the horizontal
and vertical position of the object. If either or both of the optional Boolean parameters horizontal or vertical is set to
you can reset the position of the object either horizontally or vertically independently if required.

True

,

ResetDesign()

Performs Layout> Reset Design on the object.

Select()

Appends the object to the selection list of the parent score. A multiple selection consiting of any number of individual objects
can be built up by repeatedly calling

Select

on each object you wish to add to the list. Note that calling

Select

ject will first clear any existing passage selection.

SetAllVoices()

Sets the object to be in all voices. This has no effect on some types of object, e.g. NoteRests.

54

on a BarOb-

BarObject

SetVoice(

voicenum[,clear other voices]

)

Sets the object to be in voice voicenum, optionally removing the object from all other voices if the Boolean parameter clear

True

other voices is

ShowInAll()

.

Shows the object in the full score, and in all relevant parts; equivalent to Edit> Hide or Show> Show In All.

ShowInParts()

Hides the object in the full score, and shows it in all relevant parts; equivalent to Edit> Hide or Show> Show In Parts.

ShowInScore()

Hides the object in all relevant parts, and shows it in the full score; equivalent to Edit> Hide or Show> Show In Score.

SetPlayedOnNthPass(

n, do play

)

Tells Sibelius whether or not the object should play back the nth time.

TimeOnNthPass(n)

Returns the time at which the object occurs in the score in milliseconds on the nth pass through the score, where n is an
integer specifying the pass (specify

1

for the first pass through the score), or returns -1 in the case of an error (e.g. because

the specified value of n is out of range).

Varia bles

CanBeInMultipleVoices

Color

Returns

True

if the object can be in more than one voice (read-only).

The color of this BarObject (read/write). The color value is in 24-bit RGB format, with bits 0–7
representing blue, bits 8–15 green, bits 16–23 red and bits 24–31 ignored. Since ManuScript
has no bitwise arithmetic, these values can be a little hard to manipulate; you may find the
individual accessors for the red, green and blue components to be more useful (see below).

ColorAlpha

ColorRed

ColorGreen

ColorBlue

CueSize True

The alpha channel component of the color of this BarObject, in the range 0–255 (read/write).

The red component of the color of this BarObject, in the range 0–255 (read/write).

The green component of the color of this BarObject, in the range 0–255 (read/write).

The blue component of the color of this BarObject, in the range 0–255 (read/write).

size (read/write).

CurrentTempo

DrawOrder

Returns the tempo, in bpm, at the location of the object in the score (read only).

Returns the layer at which the object is currently drawn. When used to set the layer of an
object, values from
used;
write).

Dx

The horizontal graphic offset of the object from the position implied by the
in units of 1/32 spaces (read/write).

Dy

The vertical graphic offset of the object from the centre staff line, in units of 1/32 spaces, posi­tive going upwards (read/write).

HasCustomDrawOrder

Hidden True

Returns

(read/write).

if the object is cue-size in the current part or score, and

1

(meaning the bottom layer) to 32 (meaning the highest layer) can be

0

is a special value that tells Sibelius to use the default layer for that type of object (read/

True

if the object is set to a layer other than its default layer (read only).

if the object is hidden in the current part or score, and

False

if the object is normal

Position

False

if the object is shown

field,

OnNthBlankPage

ParentBar

Returns 0 if the object occurs on a page of music, otherwise a number from 1 upwards indicat­ing the nth blank page of the bar on which the object occurs (read only).

The Bar containing this BarObject (read only).

55

Object Reference

Position

Selected

Time

Rhythmic position of the object in the bar (read only).

Returns

True

if the object is currently selected (read only).

The time at which the object occurs in the score in milliseconds; if the score contains repeats,
this will always return the time as if for the first pass through the score (read only). Returns
in the case of an error.

Type

A string describing the type of object, e.g. “NoteRest,” “Clef.” This is useful when hunting for a
specific type of object in a bar. See
possible values (read only).

UsesMagneticLayout

Returns

True

if the object is positioned by Magnetic Layout. Returns
set not to be taken into account by Magnetic Layout. To set whether or not an object should use
Magnetic Layout, use one of the global constants

Magnetic Layout> On),

DefaultDodge

UsesMagneticLayoutSettingOverridden

VoiceNumber

Voices

Returns

Is 0 if the item belongs to more than one voice (a lot of items belong to more than one voice)
and

Returns or sets Sibelius’s internal bitfield that represents the voices to which an object belongs;

True

if the object has had its Magnetic Layout settings overridden; otherwise

1

to 4 for items that belong to voices 1 to 4 (read only).

useful for copying the voices used by a given object (read/write).

GuitarScaleDiagram type values

AlwaysDodge

SuppressDodge

(Edit> Magnetic Layout> Off) or

(Edit> Magnetic Layout> Default) (read/write).

on page 161 for the

False

if the object is

(equivalent to Edit

False

-1

>

.

Deleting multiple objects from a bar

If you wish to delete multiple objects from a bar, you should first build up a list of items to delete, then iterate over the list deleting
each object in turn. It is not sufficient to simply delete the objects from the bar as you iterate over them, as this may cause the
iterator to go out of sync. Therefore, code to delete all tuplets from a bar should look something like this:

counter = 0;
for each Tuplet tup in bar {
name = "tuplet" & counter;
@name = tup;
counter = counter + 1;
}

// Delete objects in reverse order
while(counter > 0) {
counter = counter - 1;
name = "tuplet" & counter;
tup = @name;
tup.Delete();
}

56

BarRest

Derived from a BarObject object.

Methods

None.

Varia bles

PauseType

BarRest

Returns the type of fermata (pause), if any, on the bar rest. Returns one of the constants

(0),

seTypeNone
angular

(3) (read/write).

PauseTypeSquare (1

),

PauseTypeRound (2

),

PauseTypeTri-

Pau-

RestType

Returns the type of bar rest via one of the constants
(1),

OneBarRepeat (2

a bar rest of a particular type, use

),

TwoBarRepeat (3

bar.InsertBarRest()

),

FourBarRepeat (4

WholeBarRest (0

) (read only). To create

(see above).

),

BreveBarRest

57

Object Reference

Bracket

Accessed from a BracketsAndBraces object.

Methods

None.

Varia bles

BottomStave

Returns the Staff object at which the bracket ends, relative to the current part.

BottomStaveNum

BracketType

TopStave

TopStaveNum

Returns the number of the bottom staff included in the bracket, relative to the current part.

Returns the type of the bracket:

Returns the Staff object at which the bracket starts, relative to the current part.

Returns the number of the top staff included in the bracket, relative to the current part.

BracketFull, BracketBrace

or

BracketSub

.

58

BracketsAndBraces

BracketsAndBraces

Accessed from a Score object. Describes the brackets (which may be brackets, sub-brackets or braces) present in the score.

for each

Array access

bracket in iterates through all the brackets in the list.

[

int n] returns the nth bracket in the list, or null if the bracket does not exist.

Methods

AddBracket(

Creates a bracket of a given type, spanning the range of staves specified between top staff number and bottom staff number
inclusive, and returns the new Bracket object. The staff numbers are relative to the current part view. Values for type are

BracketFull (0

ClearAll()

Removes all existing brackets, sub-brackets and braces from the current part, and returns the number of brackets removed.

DeleteNthBracket(n)

Deletes the nth bracket from the current part, and returns True if successful.

type, top staff number, bottom staff number

),

BracketBrace (1

) and

BracketSub (2

)

).

Varia bles

NumChildren

Returns the number of child brackets, sub-brackets and braces in the list.

59

Object Reference

Clef

Derived from a BarObject

Methods

None.

Varia bles

ClefStyle

The name of this clef, which may be different depending on the state of Notes> Transpos­ing Score (read only).

ConcertClefStyleId

ConcertClefStyle

StyleId

TransposingClefStyle

TransposingClefStyleId

The concert pitch identifier of the style of this clef (read only).

The concert pitch name of this clef (read only).

The identifier of the style of this clef, which may be different depending on whether or not

>

Notes

method to create a clef of this style (read only).

The transposing score name of this clef (read only).

The transposing score identifier of the style of this clef (read only).

Transposing Score is switched on. This can be passed to the

Bar.AddClef

60

Comment

Derived from a BarObject.

Methods

None; create via

Varia bles

Maximized

Bar

Comment

object.

Returns True if the comment is maximized, otherwise returns False (read/write).

Text

TextWithFormatting

arr[0] = “This text is “
arr[1] = “\B\”
arr[2] = “bold”
arr[3] = “\b\”
arr[4] = “, and this is “
arr[5] = “\I\”
arr[6] = “italic”
arr[7] = “\i\”

TextWithFormattingAsString

TimeStamp

UserName

Returns the text of the comment (read/write).

Returns an array containing the various changes of font or style (if any) within the
comment’s text in a new element (read only). For example, “This text is \B\bold\b\,
and this is \I\italic\i\” would return an array with eight elements containing the fol­lowing data:

The comment’s text including any changes of font or style (read only).

Returns a

DateTime

object corresponding to the date the comment was created or last

edited (read only).

Returns the username of the user who created or last edited the comment (read only).

61

Object Reference

ComponentList

An array that is obtained from

each

loop or as an array with the

Methods

None.

Varia bles

NumChildren

Sibelius.HouseStyles

[n]

operator to access each Component object:

Number of plug-ins (read only).

or

Sibelius.ManuscriptPapers

. It can be used in a

for

62

Component

This represents a Sibelius “component,” namely a house style or a manuscript paper. Examples:

// Create a new score using the first manuscript paper
papers=Sibelius.ManuscriptPapers;
score=Sibelius.New(papers[0]);
// Apply the first house style to the new score
styles=Sibelius.HouseStyles;
score.ApplyStyle(styles[0], "ALLSTYLES");

Methods

None.

Varia bles

Name

The name of the component (read only).

Component

63

Object Reference

DateTime

This object returns information about the current date and time.

Methods

None.

Varia bles

Seconds

Returns the number of seconds from the time in a date (read only).

Minutes

Hours

DayOfMonth

Month

Year

NthDayOfWeek

NthDayOfYear

LongDate

ShortDate

LongDateAndTime

ShortDateAndTime

TimeWithSeconds

TimeWithoutSeconds

Returns the number of minutes from the time in a date (read only).

Returns the number of hours from the time in a date (read only).

returns the nth day on the month, 1-based (read only).

returns the nth month of the year, 1-based (read only).

returns the year (read only).

returns the nth day of the week, 0-based (read only).

returns the nth day of the year, 0-based (read only).

returns the date in a human-readable format, e.g. 1st May 2008 (read only).

returns the date in a human-readable format, e.g. 01/05/2008 (read only).

returns the date and time in a human-readable format, e.g. 1st May 2008 14:07 (read
only).

returns the date and time in a human-readable format, e.g. 01/05/2008 14:07 (read only).

returns the time in a human-readable format, e.g. 14:07 (read only).

returns the time in a human-readable format, e.g. 14:07:23 (read only).

64

Dictionary

Dictionary

For more details about using dictionaries in ManuScript, see

To create a dictionary, use the built-in function

CreateDictionary(

Dictionary

on page 22.

name1, value1, name2, value2, ... nameN, valueN).

This creates a dictionary containing user properties called name1, name2, nameN with values value1, value2, valueN respectively.

To iterate over dictionaries:

*

To iterate over element values in Dictionary objects, use

Dictionary

*

To iterate over element names in Dictionary objects, use

*

To iterate over
Dictionary object: n

value.name

.Name

is the element name, n

pairs in Dictionary objects, use

.Value

for each

for each Name

n

for each Pair

is the element value.

in Dictionary

n

in Dictionary

n

in Dictionary

or

for each Value

; this returns a new

Methods

CallMethod(

Calls the specified method methodname in the dictionary, passing in any other values that are required for the method as
further parameters.

GetMethodNames()

Returns a sparse array containing the names of the methods belonging to a dictionary.

GetPropertyNames()

Returns a sparse array of the names of all the user properties in the dictionary (same as

MethodExists(

Returns

methodname,param1,param2,...paramN

methodname

True

if the specified method methodname exists in the dictionary.

)

)

_propertyNames

).

n

in

PropertyExists(

Returns

SetMethod(

True

Binds a method to the dictionary.
refers to the plug-in in which the method is found, and

propertyname

)

if the specified user property propertyname exists in the dictionary.

methodname

,Self,

method

)

methodname

is the name by which you want to access the method via the dictionary,

method

is the name of the method itself, found elsewhere in the plug-in.

Varia bles

None.

Converting old-style hash tables to dictionaries

The Dictionary object is, among other things, a replacement for the old Hash object, which was a simple hash table object. You are
recommended to use the new Dictionary object instead of the old Hash object in your plug-ins, but if you have an existing plug-in
in which old-style hashes are used, you can convert them to Dictionaries as follows:

Hash.ConvertToDictionary()

returns a new Dictionary object, populated with strings converted from the old-style Hash.

Self

65

Object Reference

DocumentSetup

Accessed from a Score object. Corresponds to the settings in Layout> Document Setup.

When you first access the DocumentSetup object, the units default to millimetres; if you want to use another unit of
measurement, set

DocumentSetup.Units

displayed in Layout

>

Document Setup; to do that, set

before you set any of the other values. This will not, however, change the units

DocumentSetup.UnitsInDocumentSetupDialog

.

Be careful also that if you set

DocumentSetup.PageHeight

DocumentSetup.PageSize

, the page size specified will override any custom height/width you may have just set: so set

the page size before you then adjust the width or height of the page.

Methods

None.

Varia bles

AboveTopStaveGap

AboveTopStaveGapAfterFirstPage

BelowBottomStaveGap

BelowBottomStaveGapAfterFirstPage

FirstPageHasUniqueVerticalStaveMargins

Returns or sets the top staff margin on each page in the units specified by the
(read/write).

Returns or sets the top staff margin on pages after the first page in the units specified by the

Units

variable (read/write). To set this, first set

to

StaveMargins

True

Returns or sets the bottom staff margin on each page in the units specified by the
variable (read/write). To set this, first set

to

True

Margins

.

Returns or sets the bottom staff margin on each page after the first page in the units specified

Units

by the

Returns

variable (read/write).

True

if the After first page checkbox is switched on in Document Setup, spec­ifying that the first page of the score has different top and bottom staff margins to subsequent
pages; otherwise returns

.

False

after setting

(read/write).

DocumentSetup.PageWidth

Units

FirstPageHasUniqueVertical-

FirstPageHasUniqueVerticalStave-

or

variable

Units

Orientation

PageHeight

PageSize

PageWidth

MarginType

PageBottomMargin

PageLeftMargin

PageRightMargin

66

Returns or sets the current page orientation. Values are

OrientationLandscape (1
PageTopMargin
PageRightMargin

and

PageBottomMargin

values, to reflect the change in orientation (read/write).

). If you change the orientation, this will swap the

values with the

Returns or sets the height of a page in the units specified by the

Returns or sets the current page size. Values are listed in
you attempt to set
page size, set

PageSize

PageWidth

value will also change the

to

PageSizeCustom

and

PageHeight

PageWidth

and

PageHeight

individually. Setting any default

Returns or sets the width of a page in the units specified by the

Returns or sets the current page margin type. Values are

PageMarginsMirrored (1

),

PageMarginsDifferent (2

OrientationPortrait (0

PageLeftMargin

Units

PageSize values

, Sibelius will do nothing; to set a custom

values (read/write).

Units

PageMarginsSame (0

) (read/write).

Returns or sets the bottom page margin in the units specified by the
write).

Returns or sets the left page margin in the units specified by the

Units

Returns or sets the right page margin in the units specified by the
write).

) and

and

variable (read/write).

on page 162. If

PageSize

variable (read/write).

Units

variable (read/

variable (read/write).

Units

variable (read/

),

DocumentSetup

PageTopMargin

RightPageLeftMargin

Returns or sets the top page margin in the units specified by the

Returns or sets the left page margin for right-hand pages in the units specified by the
variable (read/write). Setting this value automatically sets

PageMarginsDifferent

RightPageRightMargin

Returns or sets the right page margin for right-hand pages in the units specified by the
variable (read/write). Setting this value automatically sets

PageMarginsDifferent

StaffLeftMarginFullNames

Returns or sets the margin to the left of staves showing full instrument names in the units
specified by the

StaffLeftMarginNoNames

Returns or sets the margin to the left of staves showing no instrument names in the units
specified by the

StaffLeftMarginShortNames

Returns or sets the margin to the left of staves showing short instrument names in the units
specified by the

StaffSize

Units

Returns or sets the staff size in the units specified by the

Returns or sets the units of measurement for all of the relevant variables of the DocumentSetup
object. Always returns

DocumentSetupUnitsInches (1

Units

variable (read/write).

Units

variable (read/write).

Units

variable (read/write).

0

(millimeters). Values are

Units

variable (read/write).

Units

MarginType

to

.

Units

MarginType

to

.

Units

variable (read/write).

DocumentSetupUnitsmm (0

),

DocumentSetupUnitsPoints (2

) (read/write).

),

UnitsInDocumentSetupDialog

Returns or sets the units of measurement currently shown in the Layout> Document
Setup dialog. Values are as for

Units

.

67

Object Reference

DynamicPartCollection

Accessed from a Score object. Contains DynamicPart objects.

The DynamicPartCollection object always contains the full score as the first entry, whether or not any dynamic parts exist. The
DynamicPart objects are returned in the order in which they were created (the last part returned is the most-recently created
one). For scores in which dynamic parts were generated automatically, the parts will normally be returned in top to bottom score
order.

The edit context for ManuScript is stored in the score itself which means that ManuScript can only ever access one part at a time –
the “current” DynamicPart for that Score object. This is irrespective of the number of score windows open for a score, which
dynamic parts are open, and even if the user has managed to create two different ManuScript Score objects referring to the same
Sibelius score.

It is inadvisable to modify Staves, Bars, or any BarObjects that do not exist on Staves in
Doing so will create part overrides for part-specific properties of these objects which will be invisible until those Staves are added
to the part.

Both DynamicPartCollection and DynamicPart refer to an underlying Score and part(s) and will generate errors if the Score and/
or part(s) are no longer valid (e.g. if a DynamicPart has been deleted). DynamicParts are never “re-used.” For example, if you
delete a DynamicPart and create a new DynamicPart, the old ManuScript DynamicPart object will not refer to the newly-created
DynamicPart.

for each

Adding or deleting parts while iterating will have undefined results, and is not recommended.

Array access [int n] returns the nth part (

DynamicPart.IncludesStaff()

variable in iterates through all valid DynamicPart objects for the Score, always starting first with the full score.

0

is always the full score), or null if the part does not exist.

can be used to test if a DynamicPart contains a particular Staff object.

Score.CurrentDynamicPart

Methods

CreateDefaultParts()

Creates the default set of dynamic parts, as created automatically by Sibelius when clicking the New Part button in the Parts

False

window. This method does nothing and returns

CreatePartFromStaff(

Creates a dynamic part from the specified Staff object, if valid. Returns the new DynamicPart object for success, or null for
failure.

DeletePart(

dynamic part

staff

)

)

if the Score has no staves.

.

Deletes the specified part, if it’s valid. Returns
part is the currently active part for the Score, or is the full score, or refers to a different Score.

True

for success,

False

for failure. This method fails is the specified dynamic

Varia bles

NumChildren

68

Returns the number of DynamicPart objects for the Score returned by iteration (read only).

DynamicPart

Accessed from a DynamicPartCollection object.

DynamicPart

for each

is not included in

variable in returns the Staff objects in the dynamic part, in top to bottom order. Warning: this can return a Staff that

Score.CurrentDynamicPart

.

Methods

AddStaffToPart(

Adds the specified staff to the bottom of the dynamic part. Returns
called on the full score, or if attempting to add a staff that is already present in the part or a staff from a different score.

DeleteStaffFromPart(

Deletes the specified staff from the dynamic part. Returns False for failure. This method will cause an error if called on the full
score, or if attempting to delete a staff that is not present in the part, or if deleting the last staff in a part, or attempting to delete
a part from a different score.

IncludesStaff(

Returns

True

staff

)

staff

)

staff

)

if the specified staff is contained in this dynamic part.

False

for failure. This method will cause an error if it is

Varia bles

IsFullScore

IsSelectedInPartsWindow

StaveCount

ParentScore

Returns

Returns

True

if this is the full score (read only).

True

if the part is selected in the Parts window (read only).

Returns the number of staves in the part (read only).

Returns the Score object containing this dynamic part (read only).

69

Object Reference

EngravingRules

Accessed via the Score object. Corresponds to selected settings in the House Style> Engraving Rules dialog.

Methods

None.

Varia bles.

AdjustTranspositionIfKeySigWraps

Returns

False

ments in remote keys option on the Clefs and Key Signatures page (read/write).

True

if Sibelius will adjust note spelling for transposing instruments in extreme keys,

otherwise; corresponds to the Adjust note spelling in transposing instru-

BarlineWidth

BeamThickness

Returns or sets the width of normal barlines in spaces, from the Barlines page (read/write).

Returns or sets the thickness of beams in spaces, from the Beams and Stems page (read/
write).

CautionaryNaturalsInKeySignatures

Returns

True

if key changes will show cautionary naturals;
and Key Signatures page (read/write).

CueNoteScale

Returns or sets the percentage by which cue-sized notes are scaled relative to normal-sized
notes, from the Notes and Tremolos page (read/write).

DashedBarlineWidth

DoubleBarlineSeparation

Returns or sets the width of dashed barlines in spaces, from the Barlines page (read/write).

Returns or sets the distance between the two lines in double barlines in spaces, from the
Barlines page (read/write).

DoubleBarlineWidth

DoubleTremoloStyle

Returns or sets the width of double barlines in spaces, from the Barlines page (read/write).

Returns or sets the style used for double tremolos in the score, from the Notes and Tremo-
los page; values are

tweenStems

(1),

write).

ExtraSpacesAboveForSystemObjectPositions

Returns or sets the n extra spaces above for System Object Positions value on the
Staves page (read/write).

False

otherwise, from the Clefs

DoubleTremolosTouchingStems (0
DoubleTremolosOuterTremoloTouchingStems (2

),

DoubleTremolosBe-

) (read/

ExtraSpacesBelowVocalStaves

Returns or sets the n extra spaces below vocal staves (for lyrics) value on the
Staves page (read/write).

ExtraSpaceBetweenGroupsOfStaves

Returns or sets the n extra spaces between groups of staves value on the Staves
page (read/write).

FinalBarlineSeparation

Returns or sets the distance between the two lines in final barlines in spaces, from the Bar­lines page (read/write).

FinalBarlineWidth

Returns or sets the width of the thick line of final barlines in spaces, from the Barlines page
(read/write).

GraceNoteScale

Returns or sets the percentage by which grace notes are scaled relative to normal notes, from
the Notes and Tremolos page (read/write).

InstrumentNamesFirstSystem

Corresponding to the option for instrument names on the first system on the Instruments

70

EngravingRules

page; values are

InstrumentNamesNone (2

InstrumentNamesNewSections

Corresponding to the option for instrument names at the start of new sections on the
Instruments page; values are
(1),

InstrumentNamesNone (2

InstrumentNamesSubsequentSystems

Corresponding to the option for instrument names on subsequent systems on the
Instruments page; values are
(1),

InstrumentNamesNone (2

JustifyGrandStaveInstruments

Returns

True

if Justify both staves of grand staff instruments on the Staves page
is switched on, otherwise

JustifyMultiStaveInstruments

Returns

True

if Justify all staves of multi-staff instruments on the Staves page is
switched on, otherwise

LegerLineThickness

Returns or sets the thickness of leger lines in spaces, from the Notes and Tremolos page
(read/write).

RespellRemoteKeysInTransposingScore

Returns

True

if Sibelius will choose the equivalent key signature with one fewer flat or sharp
for transposing instruments;
remote key signatures in transposing score on the Clefs and Key Signatures
page (read/write).

InstrumentNamesFull (0

) (read/write).

InstrumentNamesFull (0

) (read/write).

InstrumentNamesFull (0

) (read/write).

False

(read/write).

False

(read/write).

False

otherwise, corresponding to the option Respell

),

InstrumentNamesShort (1

),

InstrumentNamesShort

),

InstrumentNamesShort

),

ShowNameOfPrevailingInstrumentChangeAtStartOfSystems

Returns
the current instrument change,

True

if Sibelius will update the instrument name at the start of each system to reflect

False

otherwise; corresponds to the Change instrument

names at start of system after instrument changes option on the Instruments

page (read/write).

SlurMiddleThickness

Returns or sets the default thickness of the middle of slurs in spaces, from the Slurs page
(read/write).

SlurOutlineWidth

SmallStaffSizeScale

Returns or sets the thickness of slur ends in spaces, from the Slurs page (read/write).

Returns or sets the percentage by which small staves are scaled relative to normal-sized staves,
from the Staves page (read/write).

SpacesBetweenStaves

SpacesBetweenSystems

StaffJustificationPercentage

Returns or sets the n spaces between staves value on the Staves page (read/write).

Returns or sets the n spaces between systems value on the Staves page (read/write).

Returns or sets the Justify staves when page is at least n% full value on the Staves
page (read/write).

StaffLineWidth

StemThickness

Returns or sets the width of a staff line in spaces, from the Staves page (read/write).

Returns or sets the thickness of stems in spaces, from the Beams and Stems page (read/
write).

TieMiddleThickness

Returns or sets the thickness of the middle of ties in spaces, from the Ties 1 page (read/write).

TieOutlineWidth

Returns or sets the thickness of tie ends in spaces, from the Ties 1 page (read/write).

71

Object Reference

File

Retrievable using

for each

on a folder.

Methods

Delete()

Deletes a file, returning Tr u e if successful.

Rename(

newFileName

Renames a file, returning Tru e if successful.

)

Varia bles

CreationDate

CreationDateAndTime

ModificationDate

Name

NameWithExt

NameNoPath

Path

Type

Returns the file’s creation date and time as a DateTime object, in local time (read only).

A string giving the date and time the file was last modified in GMT (read only).

Returns the file’s modification date and time as a DateTime object, in local time (read
only).

The complete pathname of the file, no extension (read only).

The complete pathname of the file, with extension (read only).

Just the name of the file, no extension (read only).

Returns just the path to the file (read only).

A string giving the name of the type of the object; File for file objects (read only).

72

Folder

Retrievable from methods of the Sibelius object.

Folder

for each

for each

(Sibelius files), MID (MIDI files) or OPT (PhotoScore files), because they can all be opened directly by Sibelius. On the Macintosh
files of the corresponding Mac OS Type are also returned (so, for example,
end in .MID, and all files of type “Midi”).

Both these statements return subfolders recursively.

variable in produces the Sibelius files in the folder, as File objects.

type variable in produces the files of type type in the folder, where type is a Windows extension. Useful values are SIB

for each MID f

will return all files whose names

Methods

FileCount(

Returns the number of files of type Ty pe in the folder. As above, useful values are SIB, MID or OPT.

Ty pe

)

Varia bles

FileCount

FileCountAllTypes

Name

Type

The number of Sibelius files in the folder (read only).

The number of files of all types in the folder (read only).

The name of the folder (read only).

A string giving the name of the type of the object; Folder for folder objects (read only).

73

Object Reference

GuitarFrame

Derived from a BarObject. This refers to chord symbols as created by Create> Chord Symbol, whether or not they show a
guitar chord diagram (guitar frame), but is called GuitarFrame in ManuScript for historical reasons.

Methods

CopyOutSuffixes()

Returns an array containing a list of the suffix elements present in the chord. If the chord symbol is an unrecognised chord
type, the array returned will be empty. The values that can be returned in the array are as follows:

halfdim dim
add6/9 6/9
sus2/4 aug
omit5 alt
omit3 b13
maj13 #11
add13 13
maj11 11
dim13 #9
dim11 b9
maj9 b6
add9 #5
maj7 b5
dim9 #4
dim7 nc
sus9 9
sus4 7
add4 6
sus2 5
add2 m
maj /

GetChromaticPitchesOfChordInClosePosition(

consider root

)

Returns an array containing the chromatic pitches of the notes in the chord, assuming a voicing in close position. If consider
root is True (it defaults to False), the pitches returned will be offset according to the chromatic value of the root note on
which the chord is based.

GetEndStringForNthBarre(

barreNum

)

Returns the string number on which the nth barré ends.

GetPitchOfNthString(

stringNum

)

Returns the pitch of the given (open) string stringNum, as a MIDI pitch.

GetPositionOfFingerForNthBarre(

barreNum

)

Returns the fret position that the nth barré occupies.

GetPositionOfFingerOnNthString(

stringNum

)

Returns the position of the black dot representing the finger position on a given string stringNum, relative to the top of the
frame. A return value of 0 means the string is open (i.e. a hollow circle appears at the top of the diagram), and -1 means that
the string is not played (i.e. an X appears at the top of the diagram). Used in conjunction with

GetPitchOfNthString()

you can calculate the resulting pitch of each string.

GetStartStringForNthBarre(

barreNum

)

Returns the string number from which the nth barré begins.

,

74

GuitarFrame

IsNthStringPartOfBarre(

Returns

NthStringHasClosedMarkingAtNut(

True

if the given string is part of a barré.

stringNum

)

nth string

)

Returns Tru e if there’s an X marking at the top or left of the specified string.

NthStringHasOpenMarkingAtNut(

nth string

)

Returns Tru e if there’s an O marking at the top or left of the specified string.

Varia bles

BassAsString

ChordNameAsStyledString

ChordNameAsPlainText

ChromaticRoot

ChromaticBass

DiatonicRoot

DiatonicBass

The note name of the chord symbol’s altered bass note (e.g. “F”).

The name of the chord represented by this chord symbol as it appears in the score, e.g.
“Cm^7” (read only).

The name of the chord represented by this chord symbol as it appears when editing the
chord symbol, i.e. in its plain text representation, e.g. “Cmmaj7” (read only).

The chromatic pitch (C = 0, B = 11) of the chord symbol’s root note (read only).

The chromatic pitch (C = 0, B = 11) of the chord symbol’s altered bass note (read only).

The diatonic pitch, i.e. the number of the “note name” to which this note corresponds, 7
per octave (0 = C, 1 = D, 2 = E etc.), of the chord symbol’s root note (read only).

The diatonic pitch, i.e. the number of the “note name” to which this note corresponds, 7
per octave (0 = C, 1 = D, 2 = E etc.), of the chord symbol’s altered bass note (read only).

Fingerings

FrameIsVisible

Horizontal

LowestVisibleFret

NumBarresInChord

NumberOfFrets

NumberOfStrings

NumPitchesInClosePosition

Recognized

The fingerings string for this chord. This is a textual string with as many characters as the
guitar frame has strings (i.e. six for standard guitars). Each character corresponds to a gui­tar string. Use - to denote that a string has no fingering.

True if the chord symbol is currently showing a guitar chord diagram (read only).

True if the guitar chord diagram is horizontally orientated, False if it is vertically orien­tated (read/write).

The number of the top fret shown in the guitar chord diagram; setting the special value

-1

resets the lowest visible fret to the default for that chord diagram (read/write).

The number of unique barrés in the guitar chord diagram (read only).

The number of frets in the guitar chord diagram, i.e. the number of horizontal lines; set-

-1

ting the special value

resets the number of frets to the default for that chord diagram

(read/write).

The number of strings in the guitar chord diagram, i.e. the number of vertical lines (read
only).

The number of unique pitches in the chord, assuming a voicing in close position with no
duplicates.

Returns

True

if the chord symbol is a specific recognized chord type, and

False

other­wise, i.e. if the chord symbol is shown in red in the score because Sibelius is unable to parse
the user’s input (read only).

RootAsString

ScaleFactor

ShowFingerings

The note name of the chord symbol’s root (e.g. “C#”).

The scale factor of the guitar chord diagram (as adjustable via the Scale parameter on the
General panel of Properties), expressed as a percentage (read/write).

Set to

True

if the fingerings string should be displayed,

False

otherwise (read only).

75

Object Reference

SuffixText

TextIsVisible

TransposingChromaticRoot

TransposingChromaticBass

TransposingDiatonicRoot

TransposingDiatonicBass

TransposingRootAsString

TransposingBassAsString

The suffix part of the chord symbol as it appears in the score, or an empty string if the
chord isn’t recognised (read only).

True if the chord symbol is currently showing a text chord symbol (read only).

Returns the chromatic pitch of the root note for the specified chord symbol as if the score is

>

shown at transposed pitch, but regardless of whether or not Notes

Transposing

Score is switched on.

Returns the chromatic pitch of the altered bass note for the specified chord symbol, if
present, as if the score is shown at transposed pitch, but regardless of whether or not

>

Notes

Transposing Score is switched on.

Returns the diatonic pitch of the root note for the specified chord symbol as if the score is

>

shown at transposed pitch, but regardless of whether or not Notes

Transposing

Score is switched on.

Returns the diatonic pitch of the altered bass note for the specified chord symbol, if
present, as if the score is shown at transposed pitch, but regardless of whether or not

>

Notes

Transposing Score is switched on.

Returns a string representing the pitch of the root note for the specified chord symbol as if
the score is shown at transposed pitch, but regardless of whether or not Notes
Transposing Score is switched on.

Returns a string representing the pitch of the altered bass note for the specified chord
symbol, if present, as if the score is shown at transposed pitch, but regardless of whether or

>

not Notes

Transposing Score is switched on.

>

VisibleComponents

The visible parts of the chord symbol, i.e. whether it displays a text chord symbol

TextOnly

only (
and a guitar chord diagram (

), a guitar chord diagram only (

FrameAndText

), or whether or not the chord symbol shows

FrameOnly

), both a text chord symbol

a guitar chord diagram based on the type of instrument to which it is attached

InstrumentDependent

(

) (read/write).

76

GuitarScaleDiagram

Derived from a BarObject. This refers to guitar scale diagrams as created by Create > Guitar Scale Diagram.

Methods

GetDotFingeringsOnNthString(

Returns an array of strings containing the text that has been entered on the dots on a given string.

nth string

)

GuitarScaleDiagram

GetDotSymbolsOnNthString(

nth string

)

Returns an array of values describing the appearance of each of the dots on a given string. The possible values are

DotStyleCircle,DotStyleFilledCircle
DotStyleDiamond

GetPitchesOfDotsOnNthString(

,and

DotStyleFilledDiamond

nth string

,

DotStyleSquare

,

DotStyleFilledSquare

.

)

Returns an array containing the pitches of all the dots on a given string, in ascending order of pitch.

GetPitchOfNthString(

stringNum

)

Returns the pitch of the given (open) string stringNum, as a MIDI pitch.

Varia bles

Fingerings

Horizontal

LowestVisibleFret

NumberOfFrets

The fingerings string for this scale diagram. This is a textual string with as many characters as
the scale diagram has strings (i.e. six for standard guitars). Each character corresponds to a
guitar string. Use - to denote that a string has no fingering.

True if the guitar scale diagram is horizontally orientated, False if it is vertically orientated
(read/write).

The number of the top fret shown in the guitar scale diagram; setting the special value
resets the lowest visible fret to the default for that scale diagram (read/write).

The number of frets in the guitar scale diagram, i.e. the number of horizontal lines; setting the

-1

special value

resets the number of frets to the default for that scale diagram (read/write).

,

-1

NumberOfStrings

Root

ScaleFactor

ScaleType

ShowFingerings

The number of strings in the guitar scale diagram, i.e. the number of vertical lines (read only).

Returns the chromatic pitch (C = 0) of the scale’s root note (read only).

The scale factor of the guitar scale diagram (as adjustable via the Scale parameter on the
General panel of Properties), expressed as a percentage (read/write).

Returns the type of the guitar scale diagram, as specified in the list of

type values

Set to

True

on page 161 (read only).

if the fingerings string should be displayed,

False

GuitarScaleDiagram

otherwise (read only).

77

Object Reference

HitPointList

Retrievable as the
gives access to a HitPoint object. The HitPoint objects are stored in time order, so be careful if you remove or modify the time of
the objects inside a loop. If you want to change the times of all the hit points by the same value then use the
function.

HitPoints

variable of a score. It can be used in a

for each

loop or as an array with the

[n]

operator – this

ShiftTimes

Methods

Clear()

Removes all hit points from the score.

CreateHitPoint(

Creates a hit point in the score at the given time (specified in milliseconds) with a specified string label. Returns the index in
the HitPointList at which the new hit point was created.

Remove(

ShiftTimes(

index

Removes the given hit point number.

Adds the given time (in milliseconds) onto all the hit points. If the time is negative then this is subtracted from all the hit
points.

)

timeMs

timeMs,label

)

)

Varia bles

NumChildren

Number of hit points (read only).

78

HitPoint

Individual element of the HitPointList object.

Methods

None.

Varia bles

Bar

The bar in which this hit point occurs (read only).

HitPoint

Label

Position

Time

The name of the hit point (read/write).

The position within the bar at which this hit point occurs (read only).

The time of the hit point in milliseconds. Note that changing this value may change the posi­tion of the hit point in the HitPointList (read/write).

79

Object Reference

InstrumentChange

Derived from a Bar object. Provides information about any instrument changes that may exist in the score.

Methods

None.

Varia bles

StyleId

Returns the style ID of the new instrument; see

Instrument types

on page 143 (read only).

TextLabel

Returns the text that appears above the staff containing the instrument change in the score
(read only).

80

InstrumentTypeList

Contains a list of InstrumentType objects common to a given score.

InstrumentTypeList

for each

Array access [int n] returns the nth instrument type, in the same order as using a
type does not exist.

type variable in returns each instrument type in the list, in alphabetical order by the instrument type’s style ID.

Methods

None.

Varia bles

NumChildren

Returns the number of unique instrument types in the list (read only).

for each

iterator, or null if the instrument

81

Object Reference

InstrumentType

Provides information about an individual instrument type.

Methods

Clone()

Makes an exact copy of an existing instrument type.

PitchOfNthString(

string num

)

Returns the pitch of a given string in a tablature staff, with string number 0 being the lowest string on the instrument.

Varia bles

Balance

Category

ChromaticTransposition

ChromaticTranspositionInScore

ComfortableRangeHigh

ComfortableRangeLow

ConcertClefStyleId

DefaultSoundId

DiatonicTransposition

Returns the instrument’s default balance, in the range 0–

100

(read only).

Returns an index representing the category of the staff type belonging to this instrument type;

0

= pitched; 1 = percussion; 2 = tablature (read only).

Returns the number of half-steps (semitones) describing the transposition of transposing

-2

instruments; e.g. for Bb Clarinet, this returns

(read/write).

Returns the number of half-steps (semitones) describing the transposition of transposing
instruments in a score shown at concert pitch. Typically this is only used by instruments that
transpose by octaves, so this will return e.g.

for piccolo or

-12

for guitars (read only).

12

Returns the highest comfortable note (MIDI pitch) of the instrument (read only).

Returns the lowest comfortable note (MIDI pitch) of the instrument (read only).

Returns the style ID of the normal clef style of the instrument (read only).

Returns the default sound ID used by the instrument (read only).

Returns the number of diatonic steps describing the transposition of transposing instruments;

-1

e.g. for Bb Clarinet, this returns

(read/write).

DiatonicTranspositionInScore

Returns the number of diatonic steps describing the transposition of transposing instruments
in a score shown at concert pitch (read only).

DialogName

Returns the name of the instrument as displayed in the Create > Instruments dialog in
Sibelius (read/write).

FullName

Returns the name of the instrument as visible on systems showing full instrument names (read
only).

HasBracket

HasKeySignatureOrTuning

Returns

Returns
on in the Edit Staff Type dialog.

InstrumentTypeForChordDiagrams

Returns the style ID of the tab instrument type that determines the tuning used for chord
diagrams shown for this instrument, i.e. corresponding to the Tab instrument to use for
string tunings in the New/Edit Instrument dialogs.

IsVocal

Returns
that e.g. the default positions of dynamics should be above the staff rather than below (read
only).

NumStaveLines

Returns the number of staff lines in the staff (read only).

True

if the instrument has a bracket (read only).

True

if the instrument type has the Key signature / Tuning checkbox switched

True

if the instrument type used has the Vocal staff option switched on, meaning

NumStrings

82

Returns the number of strings in a tablature staff (read only).

InstrumentType

OtherClefStyleId

Pan

ProfessionalRangeHigh

ProfessionalRangeLow

ShortName

StyleId

TransposingClefStyleId

Returns the style ID of the clef style of the second staff of grand staff instruments, e.g. piano
(read only).

Returns the instrument’s default pan setting, in the range

–127

(hard left) to

127

(hard right)

(read only).

Returns the highest playable note (MIDI pitch) of the instrument for a professional player
(read only).

Returns the lowest playable note (MIDI pitch) of the instrument for a professional player (read
only).

Returns the name of the instrument as visible on systems showing short instrument names
(read only).

Returns the style ID of the instrument; see

Global constants

on page 139 (read only).

Returns the style ID of the clef to be used when Notes> Transposing Score is switched on
(read only).

83

Object Reference

KeySignature

Derived from a BarObject.

Methods

None

Varia bles

AsText

The name of the key signature as a string (read only).

IsOneStaffOnly

Major

Sharps

True if this key signature belongs to one staff only (read only).

True if this key signature is a major key (read only).

The number of sharps (positive) or flats (negative) in this key signature (read only).

84

Line

Anything you can create from the Create> Line dialog is a line object, eg. CrescendoLine, DiminuendoLine, etc. These objects
are derived from a BarObject.

Methods

None.

Varia bles

Duration

The total duration of the line, in 1/256th quarters (read/write).

Line

EndBarNumber

EndPosition

RhDx

RhDy

StyleId

StyleAsText

The bar number in which the line ends (read only).

The position within the final bar at which the line ends (read only).

The horizontal graphic offset of the right-hand side of the line, in units of 1/32 spaces (read/
write).

The vertical graphic offset of the right-hand side of the line from the centre staff line, in units
of 1/32 spaces, positive going upwards (read/write).

The identifier of the line style associated with this line (read only).

The name of the line style associated with this line (read only).

85

Object Reference

LyricItem

Derived from a BarObject

Methods

None.

Varia bles

Duration

The total duration of the lyric line, in 1/256th quarters (see

Line

on page 85) (read/write).

NumNotes

StyleAsText

StyleId

SyllableType

Text

Gives the number of notes occupied by this lyric item (read/write). Note that changing this
value will not automatically change the length of the lyric line; you also need to set the lyric
line’s

Duration

The text style name (read/write).

The identifier of the text style of this lyric (read/write).

An integer indicating whether the lyric is the end of a word (
dle of one (
appearance of hyphens that follow it.

SyllableTypes for LyricItems

see

The text as a string (read/write).

variable to the correct length.

MiddleOfWord

) (read/write). This affects how the lyric is jusitifed, and the

EndOfWord

on page 158.

EndOfWord

and

MiddleOfWord

) or the start or mid-

are global constants;

86

NoteRest

Derived from a BarObject. A NoteRest contains Note objects, stored in order of increasing diatonic pitch.

NoteRest

for each

variable in returns the notes in the NoteRest.

Methods

AddAcciaccaturaBefore(

Adds a grace note with a slash on its stem (acciaccatura) before a given NoteRest. The duration should be specified as normal,
for example, 128 would create a grace note with one beam/flag. The optional tied parameter should be
note to be tied. Voice 1 is assumed unless the optional voice parameter (with a value of 1, 2, 3 or 4) is specified. If force stem dir
is set to Tru e (the default), stems of graces notes in voices 1 and 3 will always point upwards, and stems of notes in voices 2
and 4, downwards. You can also set the diatonic pitch, i.e. the number of the “note name” to which this note corresponds, 7 per
octave (35 = middle C, 36 = D, 37 = E and so on). If a diatonic pitch of zero is given then a suitable diatonic pitch will be calcu­lated from the MIDI pitch. The optional string number parameter gives a string number for this note, which is only meaning­ful if the note is on a tablature stave. If this parameter is not supplied then a default string number is calculated based on the
current tablature stave type and the guitar tab fingering options (specified on the Note Input page of File
Returns the Note object created (to get the NoteRest containing the note, use

Note that adding a grace note before a NoteRest will always create an additional grace note, just to the left of the note/rest to
which it is attached. If you wish to create grace notes with more than one pitch, you should call
returned.

AddAppoggiaturaBefore(

Identical to

AddNote(

AddAcciaccaturaBefore

pitch[,tied[,diatonic pitch[,string number]]]

sounding pitch,[duration[,tied [,voice [,diatonic pitch[,string number[,force stem dir]]]]]]

True

>

Preferences).

Note.ParentNoteRest

).

AddNote

sounding pitch,[duration[,tied [,voice [,diatonic pitch[,string number[,force stem dir]]]]]]

, only no slash is added to the note’s stem.

)

)

if you want the

on the object

)

Adds a note with the given MIDI pitch (60 = middle C), e.g. to create a chord. The optional second parameter specifies
whether or not this note is tied (True or False). The optional third parameter gives a diatonic pitch, i.e. the number of the ‘note
name’ to which this note corresponds, 7 per octave (35 = middle C, 36 = D, 37 = E etc.). If this parameter is 0 then a default
diatonic pitch will be calculated from the MIDI pitch. The optional fourth parameter gives a string number for this note,
which is only meaningful if the note is on a tablature stave. If this parameter is not supplied then a default string number is
calculated based on the current tablature stave type and the guitar tab fingering options (specified on the Notes page of

>

Preferences). Returns the Note object created.

File

Delete()

Deletes all the notes in the NoteRest, converting the entire chord into a rest of similar duration.

FlipStem()

Flips the stem of this NoteRest – this acts as a toggle.

GetArticulation(

Returns

True

numbers are defined in

NoteRest[

array element

Returns the nth note in the chord, in order of increasing diatonic pitch (counting from 0). For example,
returns the lowest note (in terms of diatonic pitch – see

RemoveNote(

articulation number

or

False

note

)

)

depending on whether the given articulation is currently set on this note. The valid articulation

Articulations

]

on page 157.

AddNote

NoteRest[0]

below).

Removes the specified Note object.

SetArticulation(

If set is

True

, turns on the given articulation; otherwise turns it off. The valid articulation numbers are defined in

tions

on page 157.

articulation number,set

)

Articula-

87

Object Reference

Transpose(

degree, interval type[,keep double accs]

)

Transposes the entire NoteRest up or down by a specified degree and interval type. To transpose up, use positive values for
degree; to transpose down, use negative values. Note that degrees are 0-based, so 0 is equal to a unison, 1 to a second and so

on. For descriptions of the various available interval types, see

Global constants

on page 139. By default, Sibelius will

transpose using double sharps and flats where necessary, but this behavior may be suppressed by setting the keep double accs
flag to False.

For help in calculating the interval and degree required for a particular transposition, see the documentation for

Sibelius.CalculateInterval

the

and

Sibelius.CalculateDegree

methods.

Varia bles

ArpeggioDx

ArpeggioType

ArpeggioTopDy

ArpeggioBottomDy

ArpeggioHidden

Articulations

The horizontal offset of the arpeggio line on the NoteRest (read/write), in units of 1/32nd of a
space (the distance between two adjacent staff lines).

The type of note-attached arpeggio line present on the NoteRest. Values are

,

ArpeggioTypeNormal, ArpeggioTypeUp, ArpeggioTypeDown

None

ArpeggioType-

The vertical offset of the top of the note-attached arpeggio line on the NoteRest (read/write), in
units of 1/32nd of a space.

The vertical offset of the bottom of the note-attached arpeggio line on the NoteRest (read/
write), in units of 1/32nd of a space.

Returns

True

if the note-attached arpeggio line on the NoteRest is hidden (read/write).

Enables you to copy a set of articulations from one NoteRest to another (read/write), e.g:

(read/write).

destNr.Articulations = sourceNr.Articulations;

Beam

Takes values

constants

StartBeam, ContinueBeam, NoBeam

on page 139 for details). These correspond to the keys 7, 8, * (/ on Mac) and / (*

on Mac) on the third (F9) Keypad layout.

DoubleTremolos

Gives the number of double tremolo strokes starting at this note, in the range 0–7. Means noth­ing for rests. To create a double tremolo between two successive notes, ensure they have the
same duration and set the

Duration

FallDx

The duration of the note rest (read only).

The horizontal offset of a fall, if present on the NoteRest (read/write), in units of 1/32nd of a
space.

FallType

FeatheredBeamType

The type of note-attached fall present on the NoteRest. Values are

FallTypeNormal

and

Returns one of three values, based on whether a note is set to produce a feathered beam. Values

FeatheredBeamNone (0

are
(2) (read/write).

GraceNote True

HasStemlet

if it’s a grace note (read only).

Returns

True

if the note is showing a stemlet, according either to the state of the Use stem-

lets on beamed rests option on the Beams and Stems page of Engraving Rules or

the stemlet button on the Keypad (read only).

DoubleTremolos

FallTypeDoit

),

FeatheredBeamAccel (1

and

SingleBeam

of the first one (read/write).

(read/write)

) and

. (see

Global

FallTypeNone

FeatheredBeamRit

,

Highest

IsAcciaccatura True

IsAppoggiatura True

Lowest

NoteCount

88

The highest Note object in the chord (read only).

if it’s an acciaccatura, i.e. a grace note with a slash through its stem (read only).

if it’s an appoggiatura, i.e. a grace note without a slash through its stem (read only).

The lowest Note object in the chord (read only).

The number of notes in the chord (read only).

NoteRest

ParentTupletIfAny

If the NoteRest intersects a tuplet, the innermost Tuplet object at that point in the score is
returned. Otherwise, null is returned (read only).

PositionInTuplet

Returns the position of the NoteRest relative to the duration and scale-factor of its parent
tuplet. If the NoteRest does not intersect a tuplet, its position within the parent Bar is returned
as usual (read only).

RestPosition

ScoopDx

The vertical position of a rest (read/write).

The horizontal offset of a scoop or plop, if present on the NoteRest (read/write), in units of 1/
32nd of a space.

ScoopType

StemFlipped True

StemletType

The type of note-attached scoop present on the NoteRest. Values are

ScoopTypeNormal, ScoopTypePlop

Provides information about whether the NoteRest is set to display a stemlet using the options
on the Keypad. Returns either
does not show a stemlet),
show a stemlet), or
able
write).

Stemweight

Returns the stemweight of a note, taking beams into account (read only). For an unbeamed
note, this is the sum of the stave positions of all the notes in the NoteRest, where the stave
position of the middle line is zero and the position increases as you move up the stave and
decreases as you move downwards. For a beamed note, it is the sum of all the stemweights of
the NoteRests under the beam (treated as though they were unbeamed).

if the stem is flipped (read only).

StemletCustomOff

StemletCustomOn

StemletUseDefault

HasStemlet

to determine whether the NoteRest currently shows a stemlet) (read/

ScoopTypeNone

(read/write).

(in which case the NoteRest definitely

(in which case the NoteRest definitely does

(in which case you should use the read-only vari-

,

SingleTremolos

There are some special cases. If a note has its stem direction forced due to voicing, then the
stemweight will be one of the global constants

StemweightUp

or

StemweightDown

. If a

note has its stem direction forced due to the “flip” flag being set, the stemweight will be either

StemweightFlipUp

weight equal to

StemweightCross

or

StemweightFlipDown

.

. Finally, cross-stave notes have stem-

If the stemweight is less than zero, the stem will point up, otherwise it will point down.

Gives the number of tremolo strokes on the stem of this note, in the range -1 (for “z on stem”)
to 7. Means nothing for rests (read/write).

89

Object Reference

Note

Only found in NoteRests. Correspond to individual noteheads.

Methods

Delete()

Removes a single note from a chord.

Transpose(

degree, interval type[,keep double accs]

)

Transposes and returns a single Note object up or down by a specified degree and interval type*. To transpose up, use positive
values for degree; to transpose down, use negative values. Note that degrees are 0-based, so 0 is equal to a unison, 1 to a sec­ond and so on. For descriptions of the various available interval types, see

Global constants

on page 139. By default, Sibel-

ius will transpose using double sharps and flats where necessary, but this behavior may be suppressed by setting the keep
double accs flag to False. For help in calculating the interval and degree required for a particular transposition, see the docu-
mentation for the

Sibelius.CalculateInterval

and

Sibelius.CalculateDegree

methods.

* N.B.: Individual note objects cannot be transposed diatonically.

Varia bles

Accidental

AccidentalStyle

Bracketed

DiatonicPitch

IsAccidentalVisible

The accidental, for which global constants such as

Global constants

on page 139 (read only).

Sharp, Flat

and so on are defined; see

The style of the accidental (read/write). This can be any of following four global constants:

NormalAcc, HiddenAcc, CautionaryAcc

BracketedAcc

and

(which forces the accidental to be drawn inside brackets).

(which forces an accidental to appear always)

The bracketed state of the note, as shown on the F9 layout of the Keypad (read/write).

The diatonic pitch of the note, i.e. the number of the “note name” to which this note corre­sponds, 7 per octave (35 = middle C, 36 = D, 37 = E and so on) (read only).

Returns

True

if the accidental on the note is visible, i.e. the equivalent of whether or not the

corresponding button on the Keypad is illuminated for that note (read only).

Name

NoteStyle

NoteStyleName

OriginalDeltaSr

OriginalDuration

OriginalVelocity

ParentNoteRest

Pitch

Slide

The pitch of the note as a string (read only).

The index of the notehead style of this Note (read/write). The styles correspond to those acces­sible from the Notes panel of the Properties window in Sibelius; see

Note Style names

on

page 157 for a complete list of the defined NoteStyles.

The name of the notehead style of this Note (read/write). If an attempt is made to apply a non­existant style name, the note in question will retain its current notehead.

The Live start position of this notehead (in 1/256th quarters), as shown in the Playback
panel of Properties (read/write). This value can be positive or negative, indicating that the note
is moved forwards or backwards.

The Live duration of this notehead (in 1/256th quarters), as shown in the Playback panel
of Properties (read/write).

The Live velocity of this notehead (in MIDI volume units, 0-127), as shown in the Play-
back panel of Properties (read/write). Note that the word “original” refers to the fact that this
data is preserved from the original performance if the score was imported from a MIDI file or
input via Flexi-time. For further details on this value, and the ones following below, read the

Live Playback

section in Sibelius Reference.

The NoteRest object that holds this note (read only).

The MIDI pitch of the note, in semitones, 60 = middle C (read only).

Is

True

if the note has a slide,

False

otherwise (read/write).

90

Note

StringNum

The string number of this note, only defined if the note is on a tablature stave. If no string is
specified, reading this value will give –1. Strings are numbered starting at 0 for the bottom
string and increasing upwards (read only).

Tied

WrittenAccidental

WrittenDiatonicPitch

WrittenName

WrittenPitch

UseOriginalDeltaSrForPlayback

Is

True

if the note is tied to the following note (read/write).

The accidental, taking transposition into account (read only).

The written diatonic pitch of the note, taking transposition into account if

posingScore

The written pitch of the note as a string (taking transposition into account) (read only).

The written MIDI pitch of the note, taking transposition into account if

ingScore

Corresponds to the Live start position checkbox in the Playback panel of the Properties
window.

UseOriginalDurationForPlayback

sponds to the Live duration checkbox in the Playback panel of the Properties window.

UseOriginalVelocityForPlayback

sponds to the Live velocity checkbox in the Playback panel of the Properties window.

Is

Is

Is

Score.Trans-

is

True

(35 = middle C) (read only).

Score.Transpos-

is

True

(60 = middle C) (read only).

True

if the Live start position of this Note should be used for Live Playback.

True

if the Live duration of this Note should be used for Live Playback. Corre-

True

if the Live velocity of this Note should be used for Live Playback. Corre-

91

Object Reference

NoteSpacingRule

Provides access to the settings from the Appearance> House Style> Note Spacing Rule dialog. Obtained by way of the
Score object, e.g.:

nsr = Sibelius.ActiveScore.NoteSpacingRule;

Methods

None.

Varia bles

The following variables are listed in the same order as the options to which they correspond in the Note Spacing Rule dialog.

FixedBarRestWidth

The width of an empty bar if the Fixed empty bar width n spaces radio button is chosen
(read/write). This value is only used if

False

.

DetermineEmptyBarWidthBySrLength

StartOfBarGap

MinimumDurationSpace

SpaceForSixteenth

SpaceForEighth

SpaceForQuarter

SpaceForHalf

SpaceForWhole

SpaceForDoubleWhole

AllowSpaceForVoiceConflicts

The value of Before first note in bar n spaces (read/write).

The value of Short notes n spaces (read/write).

The value of 16th note (semiquaver) n spaces (read/write).

The value of 8th note (quaver) n spaces (read/write).

The value of Quarter note (crotchet) n spaces (read/write).

The value of Half note (minim) n spaces (read/write).

The value of Whole note (semibreve) n spaces (read/write).

The value of Double whole note (breve) n spaces (read/write).

Returns
wise

SpaceAroundGraceNote

ExtraSpaceAfterLastGraceNote

The value of Space around grace notes n spaces (read/write).

The value of Extra space after last grace note n spaces (read/write).

Returns
otherwise

True

False

DetermineEmptyBarWidthBySrLength

True

if Empty bar width is determined by time signature is chosen ,

False

(read/write).

if Allow extra space for colliding voices is switched on, other-

(read/write).

is

IncludeChordSymbols

ExtraSpaceBetweenGuitarFrames

MinSpaceAroundNote

MinSpaceBeforeAccidental

MinSpaceBeforeArpeggio

MinSpaceAfterHook

MinSpaceAroundLegerLine

MinSpaceAtStartOfBar

MinSpaceAtEndOfBar

MinTieSpacing

MinTieSpacingChords

IncludeLyrics

92

Returns

True

if Allow space for chord symbols is switched on, otherwise

(read/write).

The value of Minimum gap between chord symbols n spaces (read/write).

The value of Around noteheads (and dots) n spaces (read/write).

The value of Before accidentals n spaces (read/write).

The value of Before arpeggio n spaces (read/write).

The value of After tails with stems up n spaces (read/write).

The value of Around leger lines n spaces (read/write).

The value of After start of bar n spaces (read/write).

The value of Before end of bar n spaces (read/write).

The value of Min space (tie above/below note) n spaces (read/write).

The value of Min space (tie between notes) n spaces (read/write).

Returns

True

if Allow space for lyrics is switched on, otherwise

False

False

(read/write).

NoteSpacingRule

AllowFirstLyricOverhang

AllowSpaceForHyphen

SpaceBetweenLyrics

Returns

True

if Allow first lyric to overhang barline is switched on, otherwise

(read/write).

Returns

True

if Allow extra space for hyphens is switched on, otherwise

write).

The value of Minimum gap between lyrics n spaces (read/write).

False

False

(read/

93

Object Reference

PageNumberChange

Provides access to get and set the attributes of a page number change at the end of a bar or on a blank page.

Methods

SetFormatChangeOnly(

If format change only is Tru e , this has the same effect as switching off the New page number check box on the Page
Number Change dialog in Sibelius. The page numbering will therefore continue counting consecutively, but it’s possible to

(for example) hide a group of page numbers and restore visibility at a later point on the score without having to keep track of
the previous page numbers.

format change only

)

SetHideOrShow(

page number visibility

)

Takes one of the three Page number visibility global constants to determine the visibility of the initial page number
change and its subsequent pages; see

SetPageNumber(

page number

Global constants

)

on page 139.

Takes an integral number specifying the new number you wish to assign to the page.

SetPageNumberFormat(

format

)

Takes one o f t he four Page number format global constants to change the format used to display the page number
change; see

Global constants

on page 139.

Varia bles

BarNumber

HideOrShow

PageNumber

PageNumberAsString

PageNumberBlankPageOffset

PageNumberFormat

Returns the bar number expressed as an integer (read only).

Returns one of the three Page number visibility global constants; see

Global constants

on page 139 (read only).

Returns the page number expressed as an integer. For example, page x when using Roman
numerals would be 10, or 24 with alphabetics (read only).

Returns the page number change as visible on the corresponding page in Sibelius (read only).

Returns the blank page offset of the page number change, or 0 if there are no blank pages
following the bar contaning the page number change (read only).

Returns one of four Page number format global constants describing the format of the
page number change; see

Global constants

on page 139 (read only).

94

PluginList

PluginList

An array that is obtained from
to access each Plugin object.

Methods

Contains(

Returns
try to call it.

pluginName

True

if a plug-in with the given name is installed. This can be used to query whether a plugin is installed before you

Varia bles

NumChildren

Sibelius.Plugins

)

Number of plug-ins (read only).

. It can be used in a

for each

loop or as an array with the

[n]

operator

95

Object Reference

Plugin

This represents an installed plugin. Typical usage:

for each p in Sibelius.Plugins
{

trace("Plugin: " & p.Name);

}

Methods

The following methods are intended to allow you to check the existence of specific methods, data and dialogs in plug-ins, which
allows you to check in advance that e.g. calling a method in another plug-in will succeed, and fail gracefully if the method is not
found:

MethodExists(

Returns

DataExists(

Returns

DialogExists(

Returns

Varia bles

File

Name

method

)

True

if the specified method exists in the current Plugin object.

data

)

True

if the specified data exists in the current Plugin object.

dialog

)

True

if the specified dialog exists in the current Plugin object.

The File object corresponding to the file that the plug-in was loaded from (read only).

The name of the plug-in (read only).

96

RehearsalMark

RehearsalMark

Derived from a BarObject and found in the system staff only. RehearsalMarks have an internal numbering and a visible text
representation, both of which can be read from ManuScript.

Methods

None.

Varia bles

Mark

The internal number of this rehearsal mark. By default rehearsal marks are consecutive (with
the first one numbered zero), but the user can also create marks with specific numbers.

MarkAsText

The textual representation of this rehearsal mark as drawn in the score. This is determined by

>

the House Style
alphabetical).

Engraving Rules options, and can take various forms (numerical or

97

Object Reference

Score

You can obtain the Score object by way of the Sibelius object, e.g.:

score = Sibelius.ActiveScore;

A Score contains one SystemStaff and one or more Staff objects.

for each

for each

variable in returns each staff in the score or the current dynamic part in turn (not the system staff).

type variable in returns the objects in the score in chronological order, from the top staff to the bottom staff (for

simultaneous objects) and then from left to right (again, not including the system staff).

Methods

AddBars(n)

Adds n bars to the end of the score.

ApplyStyle(

Imports named styles from the given house style file (.lib) into the score. The style file parameter can either be a full path to
the file, or just the name of one of the styles that appears in the House Style
import as many “style” elements as you like in the same method. Style names are as follows:

HOUSE, TEXT, SYMBOLS, LINES, NOTEHEADS, CLEFS, DICTIONARY, SPACINGRULE, DEFAULTPARTAPPEARANCE
INSTRUMENTSANDENSEMBLES, MAGNETICLAYOUTOPTIONS

For instance:

score2.ApplyStyle("C:\NewStyle.lib", "HOUSE", "TEXT");

Note that the constant
and Layout
constant.

ClefStyleId(

style file,"style",["style"]

HOUSE

refers, for historical reasons, only to those options in the House Style> Engraving Rules

>

Document Setup dialogs, not the entire house style. To import the entire House Style, use the

clef style name

)

)

>

Import House Style dialog. You can

or

ALLSTYLES

.

,

ALLSTYLES

Returns the identifier of the clef style with the given name, or the empty string if there is no such clef style.

CreateInstrument(

Creates a new instrument, given the style ID of the instrument type required (see
want to supply the instrument names to be used in the score, set the optional change names parameter to
strings for the full name and short name. Returns

style ID[,change names,["full name",["short name"]]]

True

if the instrument was created successfully and

)

Instrument types

on page 143). If you

True

, then supply

False

if the instru-

ment type could not be found.

CreateInstrumentAtBottom(

Behaves the same way as

CreateInstrument

style ID[,change names,["full name",["short name"]]]

, only the new instrument is always created below all other instruments that

)

currently exist in the score. This can be useful when programatically copying a list of staves/instruments from one score to
another, as you can guarantee the ordering of the staves will be the same in both scores.

CreateInstrumentAtBottomReturnStave(

style ID[,change names,["full name",["short name"]]]

)

As above, but returns the Staff object created, or null if unsuccessful.

CreateInstrumentAtTop(

Behaves in exactly the same way as

style ID[,change names,["full name",["short name"]]]

CreateInstrumentAtBottom

, only the new instrument is always created above all

)

other instruments that currently exist in the score.

CreateInstrumentAtTopReturnStave(

style ID[,change names,["full name",["short name"]]]

)

As above, but returns the Staff object created, or null if unsuccessful.

98

Score

CreateInstrumentReturnStave(

Like

CreateInstrument

, but returns the Staff object created, or null if unsuccessful. Note that if the instrument being

style ID[,change names,["full name",["short name"]]]

)

created contains more than one staff (e.g. piano or harp), the top stave of the instrument in question will be returned.

ExportPartsAsPDF(

filename[,single file[,part IDs[,include score]]]

)

Exports one dynamic part, a selection of dynamic parts, or all dynamic parts in PDF format, either concatenated into a single
file, or as separate files. The filename parameter should be a complete path. It may contain the following tokens, which
Sibelius will expand automatically to generate a complete filename:

%f

= Score filename

%t

= Score title (as specified in the Title field in File> Info)

%p

= Part name (as specified in the Part name field in File> Info)

%n

= Part number

%o

= Total number of parts

%d

= Date (format YYYY-MM-DD)

%h

= Time (format HHMM)

The Boolean parameter single file specifies whether the chosen parts should be extracted into separate PDF files or concate-

True

nated into a single PDF file. This parameter defaults to

if not specified.

To specify which parts to export, create a sparse array of part IDs, and pass this in as the third parameter, part IDs. For example:

s = Sibelius.ActiveScore;
partsToExport = CreateSparseArray();
parts = s.DynamicParts;
firstNPartsToExport = 2;
i = 0;
for each part in parts {
if (i <= firstNPartsToExport) { // <= because the first "part" in the
//DynamicPartsCollection is the full score.
partsToExport.Push(part);
}
i = i + 1;
}
s.ExportPartsAsPDF("c:\\%f - %p.pdf", true, partsToExport);

To export all parts, pass in 0 instead of a sparse array.

The final optional Boolean parameter, include score, defaults to

False

. If set to

True

, the full score will also be exported

along with the parts.

ExportScoreAsPDF(

filename

)

Exports the full score as a PDF, with the specified filename, which should be a complete path. The filename parameter may use
the same tokens as the

ExtractParts(

ExportPartsAsPDF()

[show_dialogs[,parts path[,open parts]]]

Extracts parts from the score. The first optional Boolean parameter can be

method – see above.

)

False

, in which case the parts are extracted with­out showing an options dialog. The second optional parameter specifies a folder into which to extract the parts (must end with
a trailing folder separator). The third optional Boolean parameter, which defaults to

True

, specifies whether the extracted

parts should be opened immediately, or simply saved.

FreezeMagneticLayoutPositions()

Does the same as selecting the whole score and choosing Layout> Magnetic Layout> Freeze Positions, i.e. explicitly

Dx/Dy

sets the

GetLocationTime(

of every object to the position produced by Magnetic Layout, then disables Magnetic Layout for each object.

bar number[,position[,pass]]

)

Returns the time of a given bar (by passing in its bar number) and optional position within that bar in the score in
milliseconds. If the score contains repeats, the value returned will always be the time on the first pass through the score, but

99

Object Reference

you can supply the optional pass parameter to specify a particular pass in the repeat structure. If the bar and position are not

-1

valid, the return value will be

GetVersions()

Returns the score’s VersionHistory object (see

.

VersionHistory

on page 136).

HideEmptyStaves(

startStaveNum,endStaveNum,startBarNum,endBarNum

)

Hides any empty staves between startStaveNum and endStaveNum, from startBarNum to endBarNum. Both the staff numbers
and bar numbers are 1-based, and refer to the active part.

InsertBars(n,

barNum[,length]

)

Inserts n bars before bar number barNum. If no length has been specified, the bar will be created with the correct length
according to the current time signature. However, irregular bars may also be created by specifying a value for length.

InternalPageNumToExternalPageNum(

pagenum

)

Returns a string containing the external page number of the given internal page number pagenum.

LineStyleId(

line style name

)

Returns the identifier of the line style with the given name, or the empty string if there is no such line style.

NoteStyleIndex(

notehead style name

)

Returns the index of the note style with the given name, or –1 if there is no such note style.

NthStaff(

staff index from 1

)

Returns the nth staff of the score or the current dynamic part.

OptimizeStaffSpacing(

from staff number[, to staff number[,from bar[,to bar]]]

)

Does the equivalent of Layout> Optimize Staff Spacing for the given range of staves or a whole score. from staff number
must be specified; if to staff number is not specified, Sibelius will optimize the distances between from staff number and the

1

bottom staff in the score; if from bar is not specified, Sibelius sets it to

; if to bar is not specified, Sibelius sets it to the last bar

of the score.

PlayLiveTempo(

Switches Play> Live Tempo on or off; set play to

RemoveAllHighlights()

play

)

True

to switch it on, or

False

to switch it off.

Removes all highlights in this score.

RemoveVideo()

Removes an attached video from the score.

RenameTextStyle("

old name

","

new name

")

Renames a text style to a new name.

Save(

filename

)

Saves the score, overwriting any previous file with the same name.

SaveAs(

filename,type[,use_defaults,foldername]

)

Saves the score in a specified format, overwriting any previous file with the same name. The optional argument use_defaults
only applies to graphics files, and specifies whether or not the default settings are to be used. When set to False, the Export
Graphics dialog will appear and allow the user to make any necessary adjustments. The optional foldername specifies the
folder in which the file is to be saved, and will create the specified folder if it does not exist. The foldername parameter must

\\

not end with a path separator (i.e. “

” on Windows).

The possible values for type are:

SIBL
EMF

Sibelius format (current version)
EMF

100