003, 192 Digital I/O, 192 I/O, 96 I/O, 96i I/O, Adrenaline,
AirSpeed, ALEX, Alienbrain, AME, AniMatte, Archive,
Archive II, Assistant Station, AudioPages, AudioStation,
AutoLoop, AutoSync, Avid, Avid Active, Avid Advanced
Response, Avid DNA, Avid DNxcel, Avid DNxHD, Avid DS
Assist Station, Avid Ignite, Avid Liquid, Avid Media Engine,
Avid Media Processor, Avid MEDIArray, Avid Mojo,
Avid Remote Response, Avid Unity, Avid Unity ISIS,
Avid VideoRAID, AvidRAID, AvidShare, AVIDstripe, AVX,
Beat Detective, Beauty Without The Bandwidth,
Beyond Reality, BF Essentials, Bomb Factory, Bruno, C|24,
CaptureManager, ChromaCurve, ChromaWheel,
Cineractive Engine, Cineractive Player, Cineractive Viewer,
Color Conductor, Command|8, Control|24, Cosmonaut Voice,
CountDown, d2, d3, DAE, D-Command, D-Control, Deko,
DekoCast, D-Fi, D-fx, Digi 002, Digi 003, DigiBase,
Digidesign, Digidesign Audio Engine, Digidesign
Development Partners, Digidesign Intelligent Noise
Reduction, Digidesign TDM Bus, DigiLink, DigiMeter,
DigiPanner, DigiProNet, DigiRack, DigiSerial, DigiSnake,
DigiSystem, Digital Choreography, Digital Nonlinear
Accelerator, DigiTest, DigiTranslator, DigiWear, DINR,
DNxchange, Do More, DPP-1, D-Show, DSP Manager,
DS-StorageCalc, DV Toolkit, DVD Complete, D-Verb, Eleven,
EM, Euphonix, EUCON, EveryPhase, Expander,
ExpertRender, Fairchild, FastBreak, Fast Track, Film Cutter,
FilmScribe, Flexevent, FluidMotion, Frame Chase, FXDeko,
HD Core, HD Process, HDpack, Home-to-Hollywood,
HyperSPACE, HyperSPACE HDCAM, iKnowledge, Impact,
Improv, iNEWS, iNEWS Assign, iNEWS ControlAir, InGame,
Instantwrite, Instinct, Intelligent Content Management,
Intelligent Digital Actor Technology, IntelliRender, Intelli-Sat,
Intelli-Sat Broadcasting Recording Manager, InterFX,
Interplay, inTONE, Intraframe, iS Expander, iS9, iS18, iS23,
iS36, ISIS, IsoSync, LaunchPad, LeaderPlus, LFX, Lightning,
Link & Sync, ListSync, LKT-200, Lo-Fi, MachineControl,
Magic Mask, Make Anything Hollywood,
make manage move|media, Marquee, MassivePack,
MassivePack Pro, Maxim, Mbox, Media Composer,
MediaFlow, MediaLog, MediaMix, Media Reader,
Media Recorder, MEDIArray, MediaServer, MediaShare,
MetaFuze, MetaSync, MIDI I/O, Mix Rack, Moviestar,
MultiShell, NaturalMatch, NewsCutter, NewsView,
NewsVision, Nitris, NL3D, NLP, NSDOS, NSWIN, OMF,
OMF Interchange, OMM, OnDVD, Open Media Framework,
Open Media Management, Painterly Effects, Palladiium,
Personal Q, PET, Podcast Factory, PowerSwap, PRE,
ProControl, ProEncode, Profiler, Pro Tools, Pro Tools|HD,
Pro Tools LE, Pro Tools M-Powered, Pro Transfer,
QuickPunch, QuietDrive, Realtime Motion Synthesis,
Recti-Fi, Reel Tape Delay, Reel Tape Flanger,
Reel Tape Saturation, Reprise, Res Rocket Surfer, Reso,
RetroLoop, Reverb One, ReVibe, Revolution, rS9, rS18,
RTAS, Salesview, Sci-Fi, Scorch, ScriptSync,
SecureProductionEnvironment, Shape-to-Shape,
ShuttleCase, Sibelius, SimulPlay, SimulRecord,
Slightly Rude Compressor, Smack!, Soft SampleCell,
Soft-Clip Limiter, SoundReplacer, SPACE, SPACEShift,
SpectraGraph, SpectraMatte, SteadyGlide, Streamfactory,
Streamgenie, StreamRAID, SubCap, Sundance,
Sundance Digital, SurroundScope, Symphony, SYNC HD,
SYNC I/O, Synchronic, SynchroScope, Syntax,
TDM FlexCable, TechFlix, Tel-Ray, Thunder, TimeLiner,
Titansync, Titan, TL Aggro, TL AutoPan, TL Drum Rehab,
TL Everyphase, TL Fauxlder, TL In Tune, TL MasterMeter,
TL Metro, TL Space, TL Utilities, tools for storytellers, Transit,
TransJammer, Trillium Lane Labs, TruTouch, UnityRAID,
Vari-Fi, Video the Web Way, VideoRAID, VideoSPACE,
VTEM, Work-N-Play, Xdeck, X-Form, and XMON are either
registered trademarks or trademarks of Avid Technology, Inc.
in the United States and/or other countries.
Bonjour, the Bonjour logo, and the Bonjour symbol are
trademarks of Apple Computer, Inc.
Thunderbolt and the Thunderbolt logo are trademarks of Intel
Corporation in the U.S. and/or other countries.
This product may be protected by one or more U.S. and nonU.S. patents. Details are available at www.avid.com/patents.
Product features, specifications, system requirements, and
availability are subject to change without notice.
Chapter 5. Global Constants .................................................. 156
Global Constants ..................................................... 156
Contentsv
Contentsvi
Chapter 1: Introduction
ManuScript is a simple, music-based programming language used to write plug-ins for Sibelius. ManuScript 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, visit the Simkin
website at www.simkin.co.uk.
Rationale
Providing a plug-in language for Sibelius addresses several different issues:
• Music notation is complex and infinitely extensible, so some users will sometimes want to add to a music notation program to expand its possibilities with these new extensions.
• It is useful to allow frequently repeated operations (for example, 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.
Chapter 1: Introduction1
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 – please contact us at www.sibelius.com/plugins 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.
System Requirements and Compatibility Information
Avid can only assure compatibility and provide support for hardware and software it has tested and approved.
For complete system requirements and a list of qualified computers, operating systems, hard drives, and thirdparty devices, visit: www.avid.com/compatibility.
Sibelius ManuScript Language Guide2
Conventions Used in Sibelius Documentation
Sibelius documentation uses the following conventions to indicate menu choices, keyboard commands, and
mouse commands:
:
ConventionAction
File > SaveChoose Save from the File tab
Control+NHold down the Control key and press the N key
Control-clickHold down the Control key and click the mouse but-
ton
Right-clickClick with the right mouse button
The names of Commands, Options, and Settings that appear on-screen are in a different font.
The following symbols are used to highlight important information:
User Tips are helpful hints for getting the most from your Sibelius system.
Important Notices include information that could affect data or the performance of your Sibelius
system.
Shortcuts show you useful keyboard or mouse shortcuts.
Cross References point to related sections in this guide and other Avid documentation.
Chapter 1: Introduction3
Sibelius ManuScript Language Guide4
Chapter 2: Sibelius ManuScript Language
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 (such as BASIC
or C), so you’re already familiar with ideas like variables, loops, and so on.
To create a new Sibelius plug-in:
1 Start Sibelius and open or create a new score.
2 Choose File > Plug-ins > Edit Plug-ins.
Chapter 2: Sibelius ManuScript Language Tutorial5
3 The following dialog appears:
4 Click New.
5 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.
Chapter 2: Sibelius ManuScript Language Tutorial6
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.
6 Type Test as the internal name, Test plug-in as the menu name and Tests as the category name, then click OK.
7 You’ll see Test (user copy) added to the list in the Edit Plug-ins dialog under a new Tests branch of the tree
view. Click Close. This shows the folder in which the plug-in is located (Tests, 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.
8 If you look in the Home > Plug-ins gallery again you’ll see a Tests category, with a Test plug-in underneath it.
9 Choose Home > Plug-ins > Tests > 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 bothered by this warning in future.) What does our new Test plug-in do? It just pops
up a dialog which says Test (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.
10 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 lis
showing the three types of information that can make up a plug-in:
• Methods: Methods are similar to procedures, functions, or routines in some other languages.
• Dialogs: The layout of any special dialogs you design for your plug-in.
• Data: Data are 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 “Edit Plug-ins” on page 5.
t and click Edit (or simply double-click the plug-in’s name to edit it). You’ll see a dialog
Chapter 2: Sibelius ManuScript Language Tutorial7
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 sometimes 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 main() in C/C++ and Java). In other
words, when you choose
other methods, you have to call them from the Run method—otherwise how can they ever do anything?
Home > Plug-ins > Tests > Test, the plug-in’s Run method is called. If you write any
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:
Chapter 2: Sibelius ManuScript Language Tutorial8
In the top field you can edit the name; in the next field you can edit the parameters (the 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 Test 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 is a string (that is, text) it is 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 can also use Ctrl+X/C/V or
(Windows) or Control-click (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);
X/C/V for cut, copy and paste respectively. If you right-click
You can check this makes sense (or, at least, some kind of sense) by clicking the
are any blatant mistakes (e.g. missing semicolons) you will be notified where they are.
Chapter 2: Sibelius ManuScript Language Tutorial9
Check Syntax button. If there
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 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
cannot use + as this works only for numbers (if you try it in the example above, you will get an interesting answer!).
One pitfall: try changing the second line to:
x += 1;
Then click
guages but not in ManuScript. You have to do x = x+1;.
Check syntax. You will encounter an error: this syntax (and the syntax x++) is allowed in various lan-
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 plugins to these locations 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 peruser 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\Plugins.
• On Mac, additional plug-ins are stored in subfolders at /Users/username/Library/Application
Support/Avid/Sibelius/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, such as Test.plg.
(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 // is ignored to the end of
the line. Anything 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
*/
Chapter 2: Sibelius ManuScript Language Tutorial10
For instance:
Sibelius.MessageBox("Hi!"); // print the active score
or:
Sibelius /* this contains the application */ .MessageBox("Hi!");
Variables
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 does not start with a digit.
A variable can contain an integer (whole number), a floating point number, a string (text) or an object (such as
a note)—more about objects in a moment. Unlike most languages, in ManuScript a variable can contain any type
of data—you do not 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 \ as an “escape character” to represent certain special things. To include a single quote character in your strings, use \', and to include a new line you should use \n. Because of this, to include the backslash itself in a ManuScript string one has to write \\.
Converting Between Numbers, Text, and Objects
Notice that the method MessageBox is expecting to be sent some text to display. If you give it a number instead
(as in the first call to MessageBox above) the number is converted to text. If you give it an object (such as a
score), no text is produced.
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’
Chapter 2: Sibelius ManuScript Language Tutorial11
Loops
“for” and “while”
ManuScript has a while loop which repeatedly executes a block of code until a certain expression becomes
True. Create a new plug-in called Potato. This is going to amuse one and all by writing the words of the wellknown 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)
{
text = x & " potato,";
Sibelius.MessageBox(text);
x = x+1;
}
Run it. It should display “1 potato,” “2 potato,” “3 potato,” “4 potato,” which is a start, though annoyingly you
have to click
The while statement is followed by a condition in ( ) parentheses, then a block of statements in { } braces
(you don’t need a semicolon after the final
some other languages, the braces are compulsory (you can’t omit them if they only contain one statement). Moreover, each block must contain at least one statement.
In this example you can see that we are testing the value of x at the start of the loop, and increasing the value at
the end. This common construct could be expressed more concisely in ManuScript by using a for loop. The
above example could also be written as follows:
OK after each message.
} brace). While the condition is true, the block is executed. Unlike
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.
Chapter 2: Sibelius ManuScript Language Tutorial12
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;
}
The rule for
if takes the form if (condition) {statements}. You can also optionally add else
{statements}, which is executed if the condition is false. As with while, 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.
Chapter 2: Sibelius ManuScript Language Tutorial13
Now let’s make this plug-in really cool. We can build up the four messages in a variable called text, and only display it at the end, saving valuable wear on your mouse button. We can also switch round the
to show off the use of not. Finally, we return to the
for syntax we looked at earlier.
if and else blocks
text = ""; // start with no text
for x = 1 to 5
{
if (not(x=4)) {
text = text & x & " potato, "; // add some text
} else {
text = text & x & "."; // add no. 4
}
}
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)
add
subtract
multiply
divide
remainder
negate
evaluate first
ManuScript evaluates operators strictly from left-to-right, unlike many other languages; so 2+3*4 evaluates
to 20, not 14 as you might expect. To get the answer 14, you’d have to write 2+(3*4).
ManuScript also supports floating point numbers, so whereas in some early versions 3/2 would work out as 1,
it now evaluates to 1.5. Conversion from floating point numbers to integers is achieved with the
RoundUp(
expr), RoundDown(expr), and Round(expr) functions, which can be applied to any expression.
Chapter 2: Sibelius ManuScript Language Tutorial14
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 =, < and >, 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, to be a chord in your score, and (say) add more notes to it:
thischord.AddNote(60); // adds middle C (note no. 60)
thischord.AddNote(64); // adds E (note no. 64)
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 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
Chapter 2: Sibelius ManuScript Language Tutorial15
This creates a score with a Piano, and types our potato text in bar 1 as Technique text.
The code uses the period (.) several times, always in the form variable.variable or
variable.method(). This shows that the variable before the period has to contain an object.
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 some languages). For instance, if n is a variable containing a note, then
n.Pitch is a num-
ber representing its MIDI pitch (60 for middle C), and n.Name is a string describing its pitch (“C4” for middle
C). The variables available for each type of 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 containing 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.
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.
To add a bar object (i.e. an object which belongs to a bar), such as some text, to a score:
1 Specify which staff you want (and put it in a variable): staff = newscore.NthStaff(1).
2 Specify which bar in that staff you want (and put it in a variable): bar = staff.NthBar(1); finally you
tell the bar to add the text: bar.AddText(0,text,"Technique").
3 Specify the name (or index number – see Text styles on page 141) of 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.
Chapter 2: Sibelius ManuScript Language Tutorial16
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.
Chapter 2: Sibelius ManuScript Language Tutorial17
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.NoteCount which contains the number of
notes, and n.Duration which is the note-value in 1/256ths of a quarter. You can also get n.Highest and
n.Lowest which contain the highest and lowest notes (assuming n.NoteCount isn’t 0). If you set
lownote = n.Lowest, you can then find out things about the lowest note, such as lownote.Pitch
(a number) and lownote.Name (a string). Complete details about all these methods and variables may be
found in Chapter 3, “Reference.”
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 ln, then
ln.EndPosition gives the rhythmic position at which the line ends.
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 Bar object 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 Bar object
in a multiple selection. ManuScript has a for each loop that can achieve each of these in a single statement.
The simplest form of for each is like this:
thisscore = Sibelius.ActiveScore;
for each s in thisscore // sets s to each staff in turn
{ // ...do something with s
}
Here, since thisscore is a variable containing a score, the variable s is set to be each staff in thisscore
in turn. This is because staves are the type of object at the next hierarchical level of objects (see “Hierarchy of
Objects” on page 47).
For each 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 for each loop, because there is only a single Selection object; if you use the Selection
object in a for each loop, by default it will return Bar objects (not Staves, Bars or anything else!).
Chapter 2: Sibelius ManuScript Language Tutorial18
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);
}
n 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 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 Bar objects from a bar. These loops
are often nested, so you can, for instance, get several bars from several staves.
This first form of the for each loop got a sequence of objects from an object in the next level of the hierarchy of
objects. The second form of the for each 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:
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.
Chapter 2: Sibelius ManuScript Language Tutorial19
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 for each loop:
if (selection.IsPassage)
{
for each Bar b in selection
{
// do something with this bar
…
}
}
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 a separate for 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.
Chapter 2: Sibelius ManuScript Language Tutorial20
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 “unlimited” arrays. If name is a variable containing the string "x1", then @name is equivalent to
using the variable x1 directly. Thus:
i = 10;
name = "x" & i;
@name = 0;
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 CreateSparseArray
You can create an empty array simply by passing in no variables to the CreateSpareArray method.
Sparse arrays provide a read/write variable called Length that returns or sets the length of the array: when you set
Length to a number greater than the present size of the array, the array is padded with null values; if you set
Length to a number smaller 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 Push
the last element of an array, use the method Pop().
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
Chapter 2: Sibelius ManuScript Language Tutorial21
(a1, a2, ... an). To remove and return
(a1,a2,a3,a4...an).
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 ValidIndi-
ces variable. For example, using the above sparse array:
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 ofthe array, so if you do e.g. array[-100] on a six element array, you will get array[0] returned.
Some things to remember when using sparse arrays:
• Sparse arrays use a zero-based index.
• Elements that have not been initialized are null, and do not cause an error when referenced.
• Assigning to an index beyond the current length increases the Length to one greater than the index assigned
to.
• If an array contains references to objects, whether the arrays are equal or not depends on the implementation of equality for 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:
object._property: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 ob-ject.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;
Chapter 2: Sibelius ManuScript Language Tutorial22
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 runtime error.
• To check whether or not a user property has been created without causing a run-time error, use the notation
object._property:
yet.
• User properties cannot be created or accessed for normal data types (e.g. strings, integers, etc.), the global
Sibeliusobject, old-style ManuScript arrays created by CreateArray(), old-style hashes created by
CreateHash(), and null.
• User properties that conflict with an existing property name cannot be accessed as object.
ty_name
• User properties belong to a particular ManuScript object and disappear when that object’s lifetime ends. To
stop an 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.
(though they can be accessed using the ._property: notation).
property_name, which will be null if no matching user property has been created
proper-
Dictionary
Dictionary is a programmer extensible object, simply allowing the use of user properties as above with convenient construction. It also has methods allowing the use of arbitrarily 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 CreateDictionary
nameN, valueN)
. This creates a dictionary containing user properties called name1, name2, nameN with values
(name1, value1, name2, value2, ...
value1, value2, valueN respectively.
A dictionary can contain named data items (like a struct in languages like C++), or data that is indexed by
string, so that you 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.:
test = CreateDictionary("fruit",apple,"vegetable",potato);
test["fruit"] = banana;
test["meat"] = lamb;
You can even put other objects, e.g. sparse arrays, inside dictionaries, e.g.
Chapter 2: Sibelius ManuScript Language Tutorial23
You can access the user properties within a dictionary using the ._property: notation, e.g.:
return test2._property:fruit;
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 SetMethod() method, e.g.:
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, doSomething is the name of the method belonging to the dictionary, Self tells the plugin that the method is defined in the same plug-in, and pluginmethod is the name of a method elsewhere in the
plug-in (shown at the top of the example).
Chapter 2: Sibelius ManuScript Language Tutorial24
To return a sparse array containing the names of the methods belonging to a dictionary, use the dictionary’s
GetMethodNames() method. You can also check the existence of a particular method using the dictionary’s
MethodExists() 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 User properties above
can be used on data in dictionaries too.
Using User Properties as Global Variables
You can store SparseArray and Dictionary objects, and indeed any other object, as user properties of the
Plugin object itself. In the example below, Self is the object that corresponds to the running plug-in, and a
user property globalData is assigned to the plug-in, containing a Dictionary:
Self._property:globalData = CreateDictionary(1,2,3,4);
// globalData and Self.globalData can be used interchangeably
trace(globalData);
trace(Self.globalData);
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:
property_name syntax never causes run-time errors, but direct references to
property_name force a runtime error if property_name hasn't been created yet.
The example below shows how to test the existence of a specific user property, globalCounter, initialize 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 plug-in 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.
Chapter 2: Sibelius ManuScript Language Tutorial25
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.)
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
of the window, and click
Chapter 2: Sibelius ManuScript Language Tutorial26
Add. To edit an existing dialog, select it from the Dialogs list box at the top right-hand corner
Edit.
The dialog form will then appear, along with a long thin “palette” of available controls, as follows:
Radio button
Checkbox
Button
Static text
Editable text
Combo box
List box
Group box
To create a new control, just 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, use the arrow keys.
• To align controls, select them using Command-click (Mac) or Control-click (Windows), then use e.g. Command+Left Arrow (Mac) or Control+Left Arrow (Windows) to align all of the selected controls with the lefthand edge of the left-most control, or Command+Up Arrow (Mac) or Control+Up Arrow (Windows) to align
all of the selected controls with the top edge of the top-most control.
• To space controls evenly, select them using Command-click (Mac) or Control-click (Windows), then use e.g.
Command+Option+Option+Down Arrow (Mac) or Control+Alt+Shift+Down Arrow (Windows) to space the
Chapter 2: Sibelius ManuScript Language Tutorial27
controls evenly in the distance between the top edge of the top-most and the bottom edge of the bottom-most
controls, or Command+Option+Option+Left Arrow (Mac) or Control+Alt+Shift+Left Arrow (Windows) to
space the controls evenly in the distance between the left-hand edge of the 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 Command+Option+Option+Up, Down, Right, Left Arrow keys (Mac) or Control+Alt+Shift+Up, Down, Right, Left Arrow keys (Windows) 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 Command+Z (Mac) or Control+Z
(Windows) to undo and Command+Y (Mac) or Control+Y (Windows) to redo.
Testing the Dialog
To test the dialog within the editor, right-click a blank part of the dialog and choose Test from the context menu,
or type the shortcut Command+T (Mac) or Control+T (Windows). To finish testing and return to the editor, press
Esc or click any control whose properties are set to close the dialog (e.g. an
ated one).
OK or Cancel button, if you have cre-
Saving Changes
To save the changes to the dialog, click the close button in the dialog’s title bar. If there are any unsaved changes,
Sibelius prompts you to save the changes.
Chapter 2: Sibelius ManuScript Language Tutorial28
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
repeatedly hits the Tab key to cycle through them. ManuScript has a similar concept called
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 “Radio Buttons” on page 31).
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:
tab order, which refers to the order in which controls are given the focus when the user
creation order,so
To set the creation order, simply click on each control in order. If you make a mistake, press Command (Mac)
or Control (Windows) and click on the last control whose order is correct to restart the sequence from that point,
then release Command (Mac) or Control (Windows) and resume clicking on the remaining controls. Once you’re
done, press Esc to finish editing the creation order.
Chapter 2: Sibelius ManuScript Language Tutorial29
Control Properties
Every control that you create also has a Properties dialog, which can be accessed by double-clicking a selected
control, by right-clicking and choosing Properties from the context menu, or by pressing Command+Return
(Mac) or Control+Return (Windows). The dialog for a radio button control, for example, is shown below:
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
• Text: 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 correspond 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 additional options Returning True / False specify the value that the Sibelius.ShowDialog
method should return when 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.
Chapter 2: Sibelius ManuScript Language Tutorial30
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
string. Look at the variable _ComboItems in Add 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.
list of strings rather than simply a single
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.
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” on page 29). A radio button group is defined
as being all the radio buttons created between 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).
Chapter 2: Sibelius ManuScript Language Tutorial31
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
presses Return or Enter on their keyboard, the dialog is confirmed, and closes. Likewise, you will want the
cel
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 True. Depending on the other controls in your dialog, you may additionally
want to check
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.
Give this control focus; if you have one or more edit controls in the dialog, you should probably
Can-
Debugging 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
In the unlikely event that 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 be that Sibelius will crash.
Other page of File > Preferences to its leftmost position).
Plug-in Trace Window
The trace window can be shown by choosing Plug-ins > Plug-in Trace Window. A special ManuScript command, trace(
your plug-in is doing at 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.
One potential pitfall with the trace(
jects 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
Chapter 2: Sibelius ManuScript Language Tutorial32
string), will print the specified string in the trace window. This is useful to keep an eye on what
string)approach to debugging is that the built-in hash table and array ob-
whole structure of the array or hash at that point. So we could trace the current value of an array variable as follows:
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 ValidationChecking(
object2]...]
checking is enabled for all types of objects, and all plug-ins. If you supply one or more object parameters (e.g.
Tuplet, Score, BarObject, etc.), only those objects will be checked, and only in the currently running
plug-in. You should ensure ValidationChecking is set to false before you give your plug-ins to anybody
else to use.
You can also use the special method IsValid() to determine whether an object is valid: it will return false
if the object in question no longer exists. GetValidationError(
is no error, or returns a string if an error has occurred, use trace(GetValidationError(score)); to
trace any validation error returned by a Score object to the trace window.
), and set the Boolean parameter enable to true. If enable is the only parameter, validation
object) returns an empty string if there
enable[, object1[,
Stopping the Plug-in
If you want to force your plug-in to stop on a particular error condition, use StopPlugin([message]), which
will stop your plug-in, display the optional message in an alert box, and open the plug-in editor at the line of code
reached.
You can also use ExitPlugin(), which exits the plug-in cleanly without dropping into the plug-in editor.
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
strings, if required.
Chapter 2: Sibelius ManuScript Language Tutorial33
key (the name of the string) and a value (the contents of the string). The value can also be an array of
Initializing the Database
errorcode = Open(pluginname,featureset);
Open the library and lock for exclusive access by the calling plug-in. The calling plug-in is identified with the
string
pluginname. It is recommended that this string equals the unique Sibelius menu name of the calling plug-
in.
Parameter
set is currently 020000. Each library release shows in its initial dialog a list of supported feature sets. The call to
Open() will fail and show 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 CheckFeatureSet() first.
After Open() the scope is undefined, such that you can access only global variables until the first call to
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.
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(
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.
featureset is the version of the feature set requested by the calling plug-in. The version of the feature
• -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
featureset);
errorcode = Close();
Release the exclusive access lock to the library. If there were any changes since the last call to Open() or
Write(), dump the 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.
errorcode = CloseWithoutWrite();
Release the exclusive access lock to the library, discarding any changes performed since last call to Open() or
Write().
Chapter 2: Sibelius ManuScript Language Tutorial34
Return value: CloseWithoutWrite() returns zero or a positive value on success. A negative result indicates
that there was a fatal error, namely that the database was not open at the moment.
errorcode = Write(
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.
dirty);
Accessing Data
index = SetKey(keyname, value);
Store a string
of the same
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 SetKey() for local keys if the scope is undefined.
Return value: SetKey() returns zero or a positive value on success, and a negative value upon error.
errorcode = SetArray(
Store an
rays of the same
natural size of the array, i.e., array.NumChildren.
value under the name keyname in the database, overwriting any previously stored keys or arrays
keyname.
keyname, array, size);
array of strings under the name keyname in the database, overwriting any previously stored keys or ar-
keyname. size specifies the number of elements in the array. A size of -1 is replaced with the
If
keyname has been declared as a local key, the array is stored within the current scope and does not affect sim-
ilar keys in other scopes. It is an error to call SetArray() for local keys if the scope is undefined.
Return value: SetArray() returns zero or a positive value on success, and a negative value upon error.
value = GetKey(
Retrieve the value of key
been stored the last time using SetArray(). For local keys, the value is retrieved from the current scope which
must not be undefined.
Return value: The value of the key or Preferences.VOID if no key of that name found.
Chapter 2: Sibelius ManuScript Language Tutorial35
keyname);
keyname from the database. It is an error to call GetKey() on an identifier which had
size = GetArray(keyname, myarray);
Retrieve the string array stored under name
an identifier which has been stored the last time by SetKey(). For local arrays, the value is retrieved from the
current scope which must not be undefined.
You must ensure before the call that
CreateArray()).
Return value: size equals the number of retrieved elements or -1 if the array was not found. Note that size might
be smaller than myarray.NumChildren, because there is currently no way to reduce the size of an already
defined array.
size = GetListOfIds(
Fill the array
Before you call this method, ensure that
CreateArray()).
Return value: returns the size of the list, which might be smaller than the natural size of the array,
myarray.Numchildren.
index = UnsetId(
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).
myarray with a list of all known Ids in the current score (or in the global scope, if undefined).
myarray);
keyname);
keyname from the database. It is an error to call GetArray() on
myarray is of ManuScript’s array type (i.e., created with
myarray is of ManuScript’s array type (i.e. created with
RemoveId(
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.
Chapter 2: Sibelius ManuScript Language Tutorial36
keyname);
Commands for Local Variables
errorcode = DeclareIdAsLocal(keyname);
Declare an identifier as a local key. Subsequent calls to Set... and Get... operations will be performed
in the scope which is set at that time. The local state is stored in the database and can be undone by a call to
DeclareIdAsGlobal or RemoveId.
Return value: Non-negative on success, negative on error.
size = GetListOfLocalIds(
Fill the array
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.
errorcode = SwitchScope(
Select scope
with no local variables. Subsequent Set... and Get... 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 to call RemoveScope() if the current scope is undefined. After the call, the database remains in
the undefined scope.
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 DeclareIdAsLocal()).
myarray with a list of all Ids declared as local. Before you call this method, ensure that myarray
scopename. If scope scopename has never been selected before, it is newly created and initialized
myarray);
scopename);
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.
Chapter 2: Sibelius ManuScript Language Tutorial37
size = GetListOfScopes(myarray);
Fill the array
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.
myarray with a list of all known scope names. You must ensure before the call that myarray is of
Miscellaneous
Trace(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
Open() call itself.
TraceData();
Writes a full dump of the data stored currently in ThisData array to the trace window. This is the full data belonging to the current plug-in. TraceData() always traces the data, regardless of the current trace level selected.
filename = GetFilename();
Return the full filename of the preferences database (including path).
Editor();
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 and DialogSpeedMode be the global variables holding the status of the checkboxes, respectively, and let DialogJobList hold the contents of the list
box item.
Chapter 2: Sibelius ManuScript Language Tutorial38
The work with the database can be reduced to four steps:
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 ...
}
}
}
2 Work with the data. After the initialization step, you can and should work with global variables
DialogDontAskAgain, DialogSpeedMode, and DialogJobList as you are used to: read from
Chapter 2: Sibelius ManuScript Language Tutorial39
them to base control flow decisions on their setting, 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.
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();
Chapter 2: Sibelius ManuScript Language Tutorial40
Chapter 3: 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:
{statements }
Block
While
for example:
{
a = 4;
}
while { expression } block
for example:
while (i < 3) {
Sibelius.MessageBox(i);
i = i + 1;
}
Chapter 3: Reference41
Switch
if else
for each
switch (test-expression) {
case (
case (case-expression-2) block ]
[
case-expression-1) block
…
[ default block ]
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-expressions, 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 statement 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]
for example:
if (found) {
Application.ShowFindResults(found);
} else {
Application.NotFindResults();
}
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 Note
Rest (such as a chord) can only contain Note objects. However, if more than one type of subobject is possible you can specify the type:
for each Type vari able in expression
block
for example:
for each NoteRest n in thisstaff {
n.AddNote(60); // add middle C
}
Chapter 3: Reference42
for
assignment
method call
self method
call
return
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:
Returns a value from a plug-in method, given by the expression. If a method doesn’t contain a
return statement, then a “null” value is returned (either the number zero, an empty string, or
the null object described below).
Expressions
Here are the operators, literals and other beasts you’re allowed in expressions.
This is a keyword referring to the plug-in owning the method. You can pass yourself
Self
nullThis is a literal object meaning “nothing.”
Identifier
member variable
Chapter 3: Reference43
to other methods, for example:
other.Introduce(Self);
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.
@to provide indirection; the identifier is then
variable.variable
This accesses a variable in another object.
integer
floating point number
string
not
and
or
equality
for example:
. 1, 100, -1
for example:
1.5, 3.15, -1.8
Text in double quotes, for example: “some text.” For strings that are rendered by
Sibelius as part of the score, i.e. the contents of some text object, there is a small but
useful formatting language 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 (\) The full list of available styling commands is as follows:
\n\New paragraph
\N\New line
\B\Bold on
\b\Bold off
\I\Italic on
\i\Italic off
\U\Underline on
\u\Underline off
\fArial Black\ Font change to Arial Black (for example)
\ctext.character.musictext\
Character style change to Music text (for example)
\f_\Font change to text style’s default font, including removing
any active character styles
\s123\Size change to 123 (units are 1/32nds of a space, not points)
\v\Vertical scale in percent
\h\Horizontal scale in percent
\t\Tracking (absolute) in 1/32nds of a space
\p\Baseline adjustment: use normal, sub (for subscript) or
super (for superscript)
\$keyword\Substitutes a string from the Score Info dialog (see below)
A consequence of this syntax is that backslashes themselves are represented by \\,
to avoid conflicting with the above commands.
The substitution command \$keyword\ supports the following keywords:
Each of these correspond to a field in the File > Score Info dialog.
not expression
Logically negates an expression, for example:
not (x=0)
expression and expression
Logical and, for example:
FoxFound and BadgerFound
expression or expression
Logical or, for example:
FoxFound or BadgerFound
expression = expression
Equality test, for example:
Name="Clock"
Chapter 3: Reference44
subtract
add
minus
concatenation
subexpression
method call
self method call
expression – expression
Subtraction, for example:
12-1
expression + expression
Addition, for example:
12+1
–expression
Inversion, for example:
-1
expression & expression
Add two strings, for example:
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
(expression)
For grouping expressions and enforcing precedence, e.g.
(4+1)*5
variable.identifier(comma-separated expressions);
for example:
x = monkey.CountBananas();
Identifier(comma-separated expressions);
Calls a method in this plug-in, for example:
x = CountBananas();
Operators
Condition Operators
You can put any expressions in parentheses after an if or while statement, but typically they will contain conditions such as
a = bequals (for numbers, text or objects)
a < bless than (for numbers)
a > bgreater than (for numbers)
c and dboth are true
c or deither are true
not cinverts a condition, e.g. not(x=4)
<=
>=greater than or equal to
!=not equal to
Use = to compare for equality, not == as found in C/C++ and Java.
Chapter 3: Reference45
= and <. The available conditions are very simple:
less than or equal to
Arithmetic
a + badd
a - bsubtract
a * bmultiply
a / bdivide
a % bremainder
-anegate
(a)evaluate first
ManuScript will evaluate expressions from left to right, so that 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 3/2 would work out as
1, it now evaluates to 1.5. Conversion from floating point numbers to integers is achieved with the
RoundUp(expr), RoundDown(expr)and Round(expr)functions, which can be applied to any expression.
2+(3*4).
Chapter 3: Reference46
Chapter 4: Object Reference
Hierarchy of Objects
Sibelius object
Score
VersionHistory
Version
VersionComment
DynamicPartCollection
EngravingRules
DynamicPart
NoteSpacingRule
Stave (including the System Stave)Selection
Bar
Text, Clef, Line, TimeSignature, KeySignature,
Highlight, Lyric, Barline, Tuplet, GuitarFrame,
GuitarScaleDiagram, Comment,
NoteRest (these are all BarObjects)
Note (in NoteRests only)
Chapter 4: Object Reference47
All Objects
Methods
AddToPluginsMenu("menu text","function name")
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 (that is 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).
CharAt(expression,position)
Returns the character from the expression at the given (zero-based) position, for example CharAt("Po-
tato",3) would give “a.”
Chr(expression)
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(expression)
Returns 1 (or True) if expression evaluates to an object rather than a null, boolean, string, or any number.
(Not to be confused with the IsPassage variable of Selection objects!)
IsValid(object)
Returns 1 (or True) if the object is valid, returns 0 (or False) if the object no longer exists (that is has been
deleted).
Chapter 4: Object Reference48
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(expression)
Returns the nearest integer to the value of the expression, for example Round(1.5) would be “2” and
Round(1.3) would be “1.”
RoundDown(expression)
Returns the nearest integer less than the value of the expression, for example RoundDown(1.5) would be “1.”
RoundUp(expression)
Returns the nearest integer greater than the value of the expression, for example RoundUp(1.5) would be “2.”
SplitString(expression,[delimiter,][trimEmpty])
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 character. If the trimEmpty parameter is True then this will ignore multiple delimiters
(which would otherwise produce some empty strings in the array). The default value of trimEmpty is False.
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, for example Substring("Potato",2) would give “tato”. When used with the optional length
parameter, Substring returns a substring of the of the expression starting from the given start position (zerobased) of the given length, for example Substring("Potato",2,2) would give “ta”.
Trace(expression)
Sends a piece of text to be shown in the plug-in trace window, for example Trace("Here
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 (such as Tuplet, Score, BarObject, and so on), only those objects will be checked, and only in the currently running plug-in. You should ensure ValidationChecking
is set to false before you give your plug-ins to anybody else to use.
User Properties
All objects (except for the Sibelius object, old-style ManuScript arrays created using CreateArray(),
old-style ManuScript hashes created using CreateHash(), and null) can also have user properties assigned
to them.
Accessibility
Accessed from the Sibelius object.
Methods
None.
Variables
ScoreDescription
Returns true if Sibelius’s built-in score description functionality is enabled (read/write).
Bar
A Bar contains BarObject objects.
for each variable in produces the BarObjects in the bar
for each type variable in produces the BarObjects of the specified type in the bar
Methods
AddBarNumber(new bar number[,format[,extra_text[,prepend[,skip this bar]]]])
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
“Global Constants” on page 156. 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 True, in which case the extra_-text is added before the numeric part of the bar number. If the optional skip this bar parameter is True, the bar
number change is created with the Don’t increment bar number option set. Returns the BarNumber object
created.
Adds a chord symbol from the given array of pitches at the specified position. The optional instrument style parameter operates the same as in the AddGuitarFrame method (see above). If the method is unable to create a
chord symbol, the method returns null; otherwise it returns the GuitarFrame object created.
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
“Clef Styles” on page 164. Alternatively you can give the name of a clef style, such as “Treble,” but bear in mind
that this may not work in non-English versions of Sibelius. Returns the Clef object created.
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 color to -1.
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 specifying a particular color, set color to -1.
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 created 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 True if successful, otherwise False.
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 center. 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 initial size. This function returns True if successful, otherwise False.
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 165. 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 finger-ings 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.
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 165 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 (that is if the clef of the new instrument is different to that of the existing instrument). show_-text is an optional boolean parameter, True if not 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 new instrument’s long name).
show_warning is an optional boolean parameter, True 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 instrument change, announcing the instrument change and giving the player time to pick up the new instrument. warn-ing_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_instru-
ment_name (or if the arguments are omitted), the instrument names will remain unchanged. Returns the In-
strumentChange object created.
Adds a key signature to the bar. The key signature is specified by text name, such as “Cb” or “C#”. The third parameter is a Boolean flag indicating if the key is major (or minor). Unless the fourth parameter is set to False,
a double barline will ordinarily be created alongside the key signature change. You may additionally hide the key
signature change by setting hidden
to True, and make the change of key appear on the bar’s parent staff only
with the one staff only flag. Returns the KeySignature object created.
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 is set to False, a double barline will ordinarily be created alongside the key signature change. You may additionally hide the key signature change by setting hidden to True, and make the
change of key appear on the bar’s parent staff only with the one staff only flag. Returns the KeySignature object created.
Adds a line to the bar. The line style can be an identifier such as “line.staff.hairpin.crescendo” or a name, such
as “Crescendo”. For a complete list of line style identifiers that can be used in any Sibelius score, see “Line
Styles” on page 160. 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.
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.
Adds a note to staff, adding to an existing NoteRest if already at this position (in which case the duration is ignored); otherwise 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 the start of the bar. The optional tied parameter should be True 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, that is 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 > Preferences). Returns the Note object created (to get the NoteRest containing the note, use
Note.ParentNoteRest).
AddPageNumber([blank page offset])
Creates and returns a page number change at the end of the bar. 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 BarObject 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.
Chapter 4: Object Reference53
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, that is 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 AddPageNumber method, it will not force a page break, so in general the AddPageNumber
method is recommended.
AddRehearsalMark([consecutive[,mark[,new prefix and suffix[,prefix[,suffx[,override defaults]]]]])
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 overridden. 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.Amark 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 True, 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(barline type[,pos])
Adds a special barline to a given position in a bar; see “Global Constants” on page 156. 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-right, top-to-bottom from zero in the top-left hand corner). Some useful symbols
have pre-defined constants; see “Global Constants” on page 156. There are also constants defined for the start of
each group in the Create > Symbol dialog, so that to access the 8va symbol, for example, you can use the index
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 created, or null if no symbol can be added to the score.
AddText(pos,text,style[,voicenum])
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 158. Alternatively you can give
the name of a text style, such as “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” on page 158. xPos and yPos are the absolute
Chapter 4: Object Reference54
position on the page. pageOffset takes a positive number for a blank page following a special page break (the first
blank page is 1), and negative for a blank page preceding the first bar of the score (the blank page immediately
before the first bar is -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 Bar.BreakType variable, and set the
number of blank pages using Bar.NumBlankPages or Bar.NumBlankPagesBefore. Then use
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.
Adds a tuplet to a bar at a given position. The left and right parameters specify the ratio of the tuplet, for example
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 parameters take one of the pre-defined constants that affect the visual
appearance of the created tuplet; see “Global Constants” on page 156. 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) for example Bar[0]
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 specified, only the items in that voice will be removed.
Delete()
Deletes and removes an entire bar from a score. This, by definition, will affect all the staves in the score.
Chapter 4: Object Reference55
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 WholeBarRest (the default if rest type is not specified), BreveBarRest,
OneBarRepeat, TwoBarRepeat and FourBarRepeat. Returns True if successful.
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 True to reset the space above the staff, and below to True to reset the space below the staff.
Respace()
Respaces the notes in this bar.
Chapter 4: Object Reference56
Variables
BarNumber
The bar number of this bar. This is the internal bar number, which always runs consecutively from 1 (read only).
BarObjectCount
The number of objects in the bar (read only).
BreakType
The break at the end of this bar, given by the constants MiddleOfSystem, EndOfSystem, MiddleOf-
Page, EndOfPage, NotEndOfSystem, EndOfSystemOrPage or SpecialPageBreak. To learn the
correspondence between these constants and the menu in the Bars panel of the Properties window, see the discussion in “Global Constants” on page 156.
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 either Bar.NumBlankPages or
Bar.NumBlankPagesBefore, or tell Sibelius to restart the music on the next left or right page with
Bar.MusicRestartsOnPage.
ExternalBarNumber
This has been deprecated as of Sibelius 5, because it can only return a number, and bar numbers that appear in
the score may now include text. Use ExternalBarNumberString instead, which 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.
ExternalBarNumberString
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.
GapAfter
Sets the gap (in spaces) after the bar (read/write)
GapBefore
Sets the gap (in spaces) before the bar (read/write).
InMultirest
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 156.
Length
The rhythmic length (read only).
Chapter 4: Object Reference57
MusicRestartsOnPage
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 is SpecialPageBreak. This variable may be set to only two of the global special page break
constants: MusicRestartsOnNextLeftPage or MusicRestartsOnNextRightPage (write only).
NthBarInSystem
Returns the position of the bar in the system, relative to the first bar on the system (bar 0) (read only).
NumBlankPages
The number of blank pages following the bar containing a special page break.
NumBlankPagesBefore
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.
OnHiddenStave
Returns True if the bar is currently hidden by way of Hide Empty Staves (read only).
OnNthPage
Returns the zero-based page number on which the bar occurs in the current part (read only).
OnNthPageExternal
Returns a string containing the external page number (which is the page number displayed in the score) of the
page in which the bar occurs.
OnNthSystem
Returns the zero-based system number (relative to its parent page) in which the bar occurs (read only).
ParentStaff
The staff containing this bar (read only).
SectionEnd
Corresponds to the Section end checkbox on the Bars panel of Properties (read/write).
Selected
Returns True if the entire bar is currently selected (read only).
SpecialPageBreakType
Returns the type of the special page break; see the documentation for the Special page break types in “Global
Constants” on page 156 (read only).
Chapter 4: Object Reference58
SplitMultirest
When True, a multirest intersecting the bar in question will be split (read/write).
Time
The time at which the bar starts in the score in milliseconds (read only).
Barline
Accessed from a Barlines object.
Methods
None.
Variables
BottomStave
Returns the Staff object at which the barline ends, relative to the current part.
BottomStaveNum
Returns the number of the bottom staff included in the barline, relative to the current part.
TopStave
Returns the Staff object at which the barline starts, relative to the current part.
TopStaveNum
Returns the number of the top staff included in the barline, relative to the current part.
Barlines
Accessed from a Score Object. Corresponds to the barline groupings in the score.
for each barline in iterates through all the barlines in the list, for example:
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.
Chapter 4: Object Reference59
Methods
AddBarline(top staff number, bottom staff number)
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(index)
Removes a given barline identified by index from the score.
Variables
NumChildren
Returns the number of unique barlines in the score (read only).
BarObject
BarObjects include Clef, Line, NoteRest, and 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 and those types are derived from the base class BarObject.)
Methods
Delete()
Deletes an item from the score. This will completely remove text objects, clefs, lines and so on 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 “Deleting Multiple Objects from a Bar” on page 64.
Deselect()
Removes the object from the selection list of the parent score. If the selection is currently a passage selection, it
is first changed to a multiple selection before the object is deselected. Returns True if the object is successfully
removed from the selection.
FreezeMagneticLayoutPositions()
Does the same as selecting an object and choosing Layout > Freeze Magnetic Layout Positions, that explicitly sets the object’s Dx/Dy to the position produced by Magnetic Layout, then disables Magnetic Layout for that
object.
GetIsInVoice(voicenum)
Returns True if the object is in the voicenum specified.
Chapter 4: Object Reference60
GetPlayedOnNthPass(n)
Returns True if the object is set to play back the nth time.
NextItem([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,or0 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: hairpin =
item.NextItem(2, “CrescendoLine”);
PreviousItem([voice[, item type]])
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 True, you can reset the position of the object either horizontally or vertically independently if
required.
ResetDesign()
Performs Layout > Reset Design on the object.
Select()
Appends the object to the selection list of the parent score. A multiple selection consisting 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 on a BarObject 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, such as NoteRests.
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 other voices is True.
ShowInAll()
Shows the object in the full score, and in all relevant parts; equivalent to Edit > Hide or Show > Show In All.
Chapter 4: Object Reference61
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 anerror (because the specified value of n is out of range).
Variables
CanBeInMultipleVoices
Returns True if the object can be in more than one voice (read-only).
Color
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
The alpha channel component of the color of this BarObject, in the range 0–255 (read/write).
ColorRed
The red component of the color of this BarObject, in the range 0–255 (read/write).
ColorGreen
The green component of the color of this BarObject, in the range 0–255 (read/write).
ColorBlue
The blue component of the color of this BarObject, in the range 0–255 (read/write).
CueSize
True if the object is cue-size in the current part or score, and False if the object is normal size (read/write).
Chapter 4: Object Reference62
CurrentTempo
Returns the tempo, in bpm, at the location of the object in the score (read only).
DrawOrder
Returns the layer at which the object is currently drawn. When used to set the layer of an object, values from 1
(meaning the bottom layer) to 32 (meaning the highest layer) can be used; 0 is a special value that tells Sibelius
to use the default layer for that type of object (read/write).
Dx
The horizontal graphic offset of the object from the position implied by the Position field, in units of 1/32
spaces (read/write).
Dy
The vertical graphic offset of the object from the center staff line, in units of 1/32 spaces, positive going upwards
(read/write).
HasCustomDrawOrder
Returns True if the object is set to a layer other than its default layer (read only).
Hidden
True if the object is hidden in the current part or score, and False if the object is shown (read/write).
OnNthBlankPage
Returns 0 if the object occurs on a page of music, otherwise a number from 1 upwards indicating the nth blank
page of the bar on which the object occurs (read only).
ParentBar
The Bar containing this BarObject (read only).
Position
Rhythmic position of the object in the bar (read only).
Selected
Returns True if the object is currently selected (read only).
Time
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 -1 in the case of an error.
Type
A string describing the type of object, such as “NoteRest,” “Clef.” This is useful when hunting for a specific type
of object in a bar. See “GuitarScaleDiagram” on page 85 for the possible values (read only).
Chapter 4: Object Reference63
UsesMagneticLayout
Returns
True if the object is positioned by Magnetic Layout. Returns False if the object is set not to be taken into ac-
count by Magnetic Layout. To set whether or not an object should use Magnetic Layout, use one of the global
constants AlwaysDodge (equivalent to Edit > Magnetic Layout > n), SuppressDodge (Edit
Layout > Off)orDefaultDodge (Edit > Magnetic Layout > Default) (read/write).
UsesMagneticLayoutSettingOverridden
Returns True if the object has had its Magnetic Layout settings overridden; otherwise False.
VoiceNumber
Is 0 if the item belongs to more than one voice (a lot of items belong to more than one voice) and 1 to 4 for items
that belong to voices 1 to 4 (read only).
Voices
Returns or sets Sibelius’s internal bit field that represents the voices to which an object belongs; useful for copying the voices used by a given object (read/write).
Magnetic
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();
}
Chapter 4: Object Reference64
BarRest
Derived from a BarObject object.
Methods
None.
Variables
PauseType
Returns the type of fermata (pause), if any, on the bar rest. Returns one of the constants PauseTypeNone
(0), PauseTypeSquare (1), PauseTypeRound (2), PauseTypeTriangular (3) (read/write).
RestType
Returns the type of bar rest via one of the constants WholeBarRest (0), BreveBarRest (1), OneBarRe-
peat(2), TwoBarRepeat (3), FourBarRepeat (4) (read only). To create a bar rest of a particular type, use
bar.InsertBarRest() (see above).
Bracket
Accessed from a BracketsAndBraces object.
Methods
None.
Variables
BottomStave
Returns the Staff object at which the bracket ends, relative to the current part.
BottomStaveNum
Returns the number of the bottom staff included in the bracket, relative to the current part.
BracketType
Returns the type of the bracket: BracketFull, BracketBrace or BracketSub.
TopStave
Returns the Staff object at which the bracket starts, relative to the current part.
Chapter 4: Object Reference65
TopStaveNum
Returns the number of the top staff included in the bracket, relative to the current part.
Brackets and Braces
Accessed from a Score object. Describes the brackets (which may be brackets, sub-brackets or braces) present
in the score.
for each bracket in iterates through all the brackets in the list.
Array access [int n] returns the nth bracket in the list, or null if the bracket does not exist.
Methods
AddBracket(type, top staff number, bottom staff number)
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), BracketBrace (1) and BracketSub (2).
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.
Variables
NumChildren
Returns the number of child brackets, sub-brackets and braces in the list.
Clef
Derived from a BarObject.
Methods
None.
Chapter 4: Object Reference66
Variables
ClefStyle
The name of this clef, which may be different depending on the state of Notes Transposing Score (read only).
ConcertClefStyleId
The concert pitch identifier of the style of this clef (read only).
ConcertClefStyle
The concert pitch name of this clef (read only).
StyleId
The identifier of the style of this clef, which may be different depending on whether or not Notes
Score is switched on. This can be passed to the Bar.AddClef method to create a clef of this style (read only).
TransposingClefStyle
The transposing score name of this clef (read only).
TransposingClefStyleId
The transposing score identifier of the style of this clef (read only).
Transposing
Comment
Derived from a BarObject.
Methods
None; create via BarObject.
Variables
Maximized
Returns True if the comment is maximized, otherwise returns False (read/write).
Text
Returns the text of the comment (read/write).
Chapter 4: Object Reference67
TextWithFormatting
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 following data:
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
The comment’s text including any changes of font or style (read only).
TimeStamp
Returns a DateTime object corresponding to the date the comment was created or last edited (read only).
UserName
Returns the username of the user who created or last edited the comment (read only).
ComponentList
An array that is obtained from Sibelius.HouseStyles or Sibelius.ManuscriptPapers. It can be
used in a for each loop or as an array with the [n] operator to access each Component object:
Methods
None.
Variables
NumChildren
Number of plug-ins (read only).
Chapter 4: Object Reference68
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.pplyStyle(styles[0], "ALLSTYLES");
Methods
None.
Variables
Name
The name of the component (read only).
DateTime
This object returns information about the current date and time.
Methods
None.
Variables
Seconds
Returns the number of seconds from the time in a date (read only).
Minutes
Returns the number of minutes from the time in a date (read only).
Hours
Returns the number of hours from the time in a date (read only).
DayOfMonth
Returns the nth day on the month, 1-based (read only).
Month
Returns the nth month of the year, 1-based (read only).
Chapter 4: Object Reference69
Year
Returns the year (read only).
NthDayOfWeek
Returns the nth day of the week, 0-based (read only).
NthDayOfYear
Returns the nth day of the year, 0-based (read only).
LongDate
Returns the date in a human-readable format, for example: 1st May 2008 (read only).
ShortDate
Returns the date in a human-readable format, for example: 01/05/2008 (read only).
LongDateAndTime
Returns the date and time in a human-readable format, for example: 1st May 2008 14:07 (read only).
ShortDateAndTime
Returns the date and time in a human-readable format, for example: 01/05/2008 14:07 (read only).
TimeWithSeconds
Returns the time in a human-readable format, for example: 14:07 (read only).
TimeWithoutSeconds
Returns the time in a human-readable format, for example: 14:07:23 (read only).
Dictionary
To create a dictionary, use the built-in function CreateDictionary(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:
1 Toiterate over element values in Dictionary objects, use for eachn in Dictionary or for each
Value n in Dictionary.
2 To iterate over element names in Dictionary objects, use for each Name n in Dictionary.
3 To iterate over value.name pairs in Dictionary objects, use for each Pair n in Dictionary;
this returns a new Dictionary object: n.Name is the element name, n.Value is the element value.
Chapter 4: Object Reference70
Methods
CallMethod(methodname,param1,param2,...paramN)
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 _propertyNames).
MethodExists(methodname)
Returns True if the specified method methodname exists in the dictionary.
PropertyExists(propertyname)
Returns True if the specified user property propertyname exists in the dictionary.
SetMethod(methodname,Self,method)
Binds a method to the dictionary. methodname is the name by which you want to access the method via the dictionary, Self refers to the plug-in in which the method is found, and method is the name of the method itself,
found elsewhere in the plug-in.
Variables
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.
Chapter 4: Object Reference71
DocumentSetup
Accessed from a Score object, DocumentSetup corresponds to the settings in Layout Document Setup.
When you first access the DocumentSetup object, the units default to millimeters; if you want to use another
unit of measurement, set DocumentSetup.Units before you set any of the other values. This will not, however, change the units displayed in LayoutDocumentSetupDialog.
Be careful also that if you set DocumentSetup.PageSize after setting DocumentSetup.PageWidth
or DocumentSetup.PageHeight, 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.
Variables
AboveTopStaveGap
Returns or sets the top staff margin on each page in the units specified by the Units variable (read/write).
AboveTopStaveGapAfterFirstPage
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 FirstPageHasUniqueVerticalStaveMargins to True.
BelowBottomStaveGap
Document Setup; to do that, set DocumentSetup.UnitsIn-
Returns or sets the bottom staff margin on each page in the units specified by the Units variable (read/write).
To set this, first set FirstPageHasUniqueVerticalStaveMargins to True.
BelowBottomStaveGapAfterFirstPage
Returns or sets the bottom staff margin on each page after the first page in the units specified by the Units variable (read/write).
FirstPageHasUniqueVerticalStaveMargins
Returns True if the After first page checkbox is switched on in Document Setup, specifying that the first page
of the score has different top and bottom staff margins to subsequent pages; otherwise returns False
(read/write).
Orientation
Returns or sets the current page orientation. Values are OrientationPortrait (0) and Orientation-
Landscape (1). If you change the orientation, this will swap the PageTopMargin and PageBottomMargin values with the PageLeftMargin and PageRightMargin values, to reflect the change in orientation
(read/write).
Chapter 4: Object Reference72
PageHeight
Returns or sets the height of a page in the units specified by the Units variable (read/write).
PageSize
Returns or sets the current page size. Values are listed in “PageSize Values” on page 200. If you attempt to set
PageSize to PageSizeCustom, Sibelius will do nothing; to set a custom page size, set PageWidth and
PageHeight individually. Setting any default PageSize value will also change the PageWidth and
PageHeight values (read/write).
PageWidth
Returns or sets the width of a page in the units specified by the Units variable (read/write).
MarginType
Returns or sets the current page margin type. Values are PageMarginsSame (0), PageMarginsMirrored
(1), PageMarginsDifferent (2) (read/write).
PageBottomMargin
Returns or sets the bottom page margin in the units specified by the Units variable (read/write).
PageLeftMargin
Returns or sets the left page margin in the units specified by the Units variable (read/write).
PageRightMargin
Returns or sets the right page margin in the units specified by the Units variable (read/write).
PageTopMargin
Returns or sets the top page margin in the units specified by the Units variable (read/write).
RightPageLeftMargin
Returns or sets the left page margin for right-hand pages in the units specified by the Units variable
(read/write). Setting this value automatically sets MarginType to PageMarginsDifferent.
RightPageRightMargin
Returns or sets the right page margin for right-hand pages in the units specified by the Units variable
(read/write). Setting this value automatically sets MarginType to PageMarginsDifferent.
StaffLeftMarginFullNames
Returns or sets the margin to the left of staves showing full instrument names in the units specified by the Units
variable (read/write).
StaffLeftMarginNoNames
Returns or sets the margin to the left of staves showing no instrument names in the units specified by the Units
variable (read/write).
Chapter 4: Object Reference73
StaffLeftMarginShortNames
Returns or sets the margin to the left of staves showing short instrument names in the units specified by the
Units variable (read/write).
StaffSize
Returns or sets the staff size in the units specified by the Units variable (read/write).
Units
Returns or sets the units of measurement for all of the relevant variables of the DocumentSetup object. Always returns 0 (millimeters). Values are DocumentSetupUnitsmm (0), DocumentSetupUnitsInches
(1), DocumentSetupUnitsPoints (2) (read/write).
UnitsInDocumentSetupDialog
Returns or sets the units of measurement currently shown in the Layout
as for Units.
Document Setup dialog. Values are
DynamicPartCollection
Accessed from a Score object. DynamicPartCollection 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 Score.Current-DynamicPart. 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. DynamicPart.IncludesStaff() can be used to test if a
DynamicPart contains a particular Staff object.
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 (for example, if a DynamicPart has been deleted).
DynamicPart 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 variable in iterates through all valid DynamicPart objects for the Score, always starting first
with the full score. Adding or deleting parts while iterating will have undefined results, and is not recommended.
Array access [int n] returns the nth part (0 is always the full score), or null if the part does not exist.
Chapter 4: Object Reference74
Methods
CreateDefaultParts()
Creates the default set of dynamic parts, as created automatically by Sibelius when clicking the New Part button
in the Parts window. This method does nothing and returns False if the Score has no staves.
CreatePartFromStaff(staff)
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)
Deletes the specified part, if it’s valid. Returns True for success, False for failure. This method fails is the
specified dynamic part is the currently active part for the Score, or is the full score, or refers to a different Score.
Variables
NumChildren
Returns the number of DynamicPart objects for the Score returned by iteration (read only).
DynamicPart
Accessed from a DynamicPartCollection object.
for each variable in returns the Staff objects in the dynamic part, in top to bottom order. Warning: this can
return a Staff that is not included in Score.CurrentDynamicPart.
Methods
AddStaffToPart(staff)
Adds the specified staff to the bottom of the dynamic part. Returns False for failure. This method will cause an
error if it is 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(staff)
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(staff)
Returns True if the specified staff is contained in this dynamic part.
Chapter 4: Object Reference75
Variables
IsFullScore
Returns True if this is the full score (read only).
IsSelectedInPartsWindow
Returns True if the part is selected in the Parts window (read only).
StaveCount
Returns the number of staves in the part (read only).
ParentScore
Returns the Score object containing this dynamic part (read only).
EngravingRules
Accessed via the Score object. Corresponds to selected settings in the House Style > Engraving Rules dialog.
Methods
None.
Variables
AdjustTranspositionIfKeySigWraps
Returns True if Sibelius will adjust note spelling for transposing instruments in extreme keys, False otherwise; corresponds to the Adjust note spelling in transposing instruments in remote keys option on the Clefsand Key Signatures page (read/write).
BarlineWidth
Returns or sets the width of normal barlines in spaces, from the Barlines page (read/write).
BeamThickness
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; False otherwise, from the Clefs and Key Signatures page (read/write).
Chapter 4: Object Reference76
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
Returns or sets the width of dashed barlines in spaces, from the Barlines page (read/write).
DoubleBarlineSeparation
Returns or sets the distance between the two lines in double barlines in spaces, from the Barlines page
(read/write).
DoubleBarlineWidth
Returns or sets the width of double barlines in spaces, from the Barlines page (read/write).
DoubleTremoloStyle
Returns or sets the style used for double tremolos in the score, from the Notes and Tremolos page; values are
Corresponding to the option for instrument names at the start of new sections on the Instruments page; values
are InstrumentNamesFull (0), InstrumentNamesShort (1), InstrumentNamesNone (2)
(read/write).
InstrumentNamesSubsequentSystems
Corresponding to the option for instrument names on subsequent systems on the Instruments page; values are
InstrumentNamesFull (0), InstrumentNamesShort (1), InstrumentNamesNone (2)
(read/write).
JustifyGrandStaveInstruments
Returns True if Justify both staves of grand staff instruments on the Staves page is switched on, otherwise
False (read/write).
JustifyMultiStaveInstruments
Returns True if Justify all staves of multi-staff instruments on the Staves page is switched on, otherwise
False (read/write).
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; False otherwise, corresponding to the option Respell remote key signatures in transposingscore on the Clefs and Key Signatures page (read/write).
Returns True if Sibelius will update the instrument name at the start of each system to reflect the current instrument change, False otherwise; corresponds to the Change instrument names at start of system after in-strument 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
Returns or sets the thickness of slur ends in spaces, from the Slurs page (read/write).
SmallStaffSizeScale
Returns or sets the percentage by which small staves are scaled relative to normal-sized staves, from the Staves
page (read/write).
SpacesBetweenStaves
Returns or sets the n spaces between staves value on the Staves
Chapter 4: Object Reference78
page (read/write).
SpacesBetweenSystems
Returns or sets the n spaces between systems value on the Staves page (read/write).
StaffJustificationPercentage
Returns or sets the Justify staves when page is at least n% full value on the Staves page (read/write).
StaffLineWidth
Returns or sets the width of a staff line in spaces, from the Staves page (read/write).
StemThickness
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).
File
Retrievable using for each on a folder.
Methods
Delete()
Deletes a file, returning True if successful.
Rename(newFileName)
Renames a file, returning True if successful.
Variables
CreationDate
Returns the file’s creation date and time as a DateTime object, in local time (read only).
CreationDateAndTime
A string giving the date and time the file was last modified in GMT (read only).
ModificationDate
Returns the file’s modification date and time as a DateTime object, in local time (read only).
Chapter 4: Object Reference79
Name
The complete pathname of the file, no extension (read only).
NameWithExt
The complete pathname of the file, with extension (read only).
NameNoPath
Just the name of the file, no extension (read only).
Path
Returns just the path to the file (read only).
Type
A string giving the name of the type of the object; File for file objects (read only).
Folder
Retrievable from methods of the Sibelius object.
for each variable in produces the Sibelius files in the folder, as File objects
for each type variable in produces the files of type in the folder, where type is a Windows extension.
Useful values are SIB (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, for each MID f will return all files whose names end in .MID, and all files of type “Midi”).
Both these statements return subfolders recursively.
Methods
FileCount(Type)
Returns the number of files of type Type in the folder. As above, useful values are SIB, MID or OPT.
Variables
FileCount
The number of Sibelius files in the folder (read only).
FileCountAllTypes
The number of files of all types in the folder (read only).
Chapter 4: Object Reference80
Name
The name of the folder (read only).
Type
A string giving the name of the type of the object; Folder for folder objects (read only).
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:
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 (that is a hollow circle appears at the top of the diagram), and -1 means that the string is not played (that is 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.
IsNthStringPartOfBarre(stringNum)
Returns True if the given string is part of a barré.
NthStringHasClosedMarkingAtNut(nth string)
Returns True if there’s an X marking at the top or left of the specified string.
NthStringHasOpenMarkingAtNut(nth string)
Returns True if there’s an O marking at the top or left of the specified string.
Variables
BassAsString
The note name of the chord symbol’s altered bass note (for example: “F”).
ChordNameAsStyledString
The name of the chord represented by this chord symbol as it appears in the score, for example: “Cm^7” (read
only).
Chapter 4: Object Reference82
ChordNameAsPlainText
The name of the chord represented by this chord symbol as it appears when editing the chord symbol, so that in
its plain text representation, for example: “Cmmaj7” (read only).
ChromaticRoot
The chromatic pitch (C = 0, B = 11) of the chord symbol’s root note (read only).
ChromaticBass
The chromatic pitch (C = 0, B = 11) of the chord symbol’s altered bass note (read only).
DiatonicRoot
The diatonic pitch, that is the number of the “note name” to which this note corresponds, 7 per octave (0 = C, 1
=D,2=Eandsoon), of the chord symbol’s root note (read only).
DiatonicBass
The diatonic pitch, that is the number of the “note name” to which this note corresponds, 7 per octave (0 = C, 1
=D,2=Eandsoon), of the chord symbol’s altered bass note (read only).
Fingerings
The fingerings string for this chord. This is a textual string with as many characters as the guitar frame has strings
(for example, six for standard guitars). Each character corresponds to a guitar string. Use to denote that a string
has no fingering.
FrameIsVisible
True if the chord symbol is currently showing a guitar chord diagram (read only).
Horizontal
True if the guitar chord diagram is horizontally orientated, False if it is vertically orientated (read/write).
LowestVisibleFret
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).
NumBarresInChord
The number of unique barrés in the guitar chord diagram (read only).
NumberOfFrets
The number of frets in the guitar chord diagram, that is the number of horizontal lines; setting the special value
-1 resets the number of frets to the default for that chord diagram (read/write).
NumberOfStrings
The number of strings in the guitar chord diagram, for example,. the number of vertical lines (read only).
Chapter 4: Object Reference83
NumPitchesInClosePosition
The number of unique pitches in the chord, assuming a voicing in close position with no duplicates.
Recognized
Returns True if the chord symbol is a specific recognized chord type, and False otherwise, that is if the chord
symbol is shown in red in the score because Sibelius is unable to parse the user’s input (read only).
RootAsString
The note name of the chord symbol’s root (for example, “C#”).
ScaleFactor
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).
ShowFingerings
Set to True if the fingerings string should be displayed, False otherwise (read only).
SuffixText
The suffix part of the chord symbol as it appears in the score, or an empty string if the chord isn’t recognized
(read only).
TextIsVisible
True if the chord symbol is currently showing a text chord symbol (read only).
TransposingChromaticRoot
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.
TransposingChromaticBass
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.
TransposingDiatonicRoot
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.
TransposingDiatonicBass
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.
TransposingRootAsString
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.
Chapter 4: Object Reference84
TransposingBassAsString
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, that is whether it displays a text chord symbol only (TextOnly), a guitar
chord diagram only (FrameOnly), both a text chord symbol and a guitar chord diagram (FrameAndText), or
whether or not the chord symbol shows a guitar chord diagram based on the type of instrument to which it is attached (InstrumentDependent) (read/write).
GuitarScaleDiagram
Derived from a BarObject. This refers to guitar scale diagrams as created by Create Guitar Scale Dia-
gram.
Methods
GetDotFingeringsOnNthString(nth string)
Returns an array of strings containing the text that has been entered on the dots on a given string.
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, DotStyleSquare, DotStyleFilledSquare,
DotStyleDiamond, and DotStyleFilledDiamond.
GetPitchesOfDotsOnNthString(nth string)
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.
Variables
Fingerings
The fingerings string for this scale diagram. This is a textual string with as many characters as the scale diagram
has strings (for example, six for standard guitars). Each character corresponds to a guitar string. Use – to denote
that a string has no fingering.
Horizontal
True if the guitar scale diagram is horizontally orientated, False if it is vertically orientated (read/write).
Chapter 4: Object Reference85
LowestVisibleFret
The number of the top fret shown in the guitar scale diagram; setting the special value -1 resets the lowest visible
fret to the default for that scale diagram (read/write).
NumberOfFrets
The number of frets in the guitar scale diagram, for example, the number of horizontal lines; setting the special
value -1 resets the number of frets to the default for that scale diagram (read/write).
NumberOfStrings
The number of strings in the guitar scale diagram, for example, the number of vertical lines (read only).
Root
Returns the chromatic pitch (C = 0) of the scale’s root note (read only).
ScaleFactor
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).
ScaleType
Returns the type of the guitar scale diagram, as specified in the list of “GuitarScaleDiagram Type Values” on
page 198 (read only).
ShowFingerings
Set to True if the fingerings string should be displayed, False otherwise (read only).
HitPointList
Retrievable as the HitPoints variable of a score. It can be used in a for each loop or as an array with the
[n] operator—this 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 ShiftTimes function.
Methods
Clear()
Removes all hit points from the score.
CreateHitPoint(timeMs,label)
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.
Chapter 4: Object Reference86
Remove(index)
Removes the given hit point number.
ShiftTimes(timeMs)
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.
Variables
NumChildren
Number of hit points (read only).
HitPoint
Individual element of the HitPointList object.
Methods
None.
Variables
Bar
The bar in which this hit point occurs (read only).
Label
The name of the hit point (read/write).
Position
The position within the bar at which this hit point occurs (read only).
Time
The time of the hit point in milliseconds. Note that changing this value may change the position of the hit point
in the HitPointList (read/write).
InstrumentChange
Derived from a BarObject. Provides information about any instrument changes that may exist in the score.
Methods
None.
Chapter 4: Object Reference87
Variables
StyleIdword
Returns the style ID of the new instrument; see “Instrument Types” on page 165 (read only).
TextLabel
Returns the text that appears above the staff containing the instrument change in the score (read only).
InstrumentTypeList
Contains a list of InstrumentType objects common to a given score.
for each type variable in returns each instrument type in the list, in alphabetical order by the instrument
type’s style ID.
Array access [int n] returns the nth instrument type, in the same order as using a for each iterator, or null if
the instrument type does not exist.
Methods
None.
Variables
NumChildren
Returns the number of unique instrument types in the list (read only).
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.
Chapter 4: Object Reference88
Variables
Balance
Returns the instrument’s default balance, in the range 0–100 (read only).
Category
Returns an index representing the category of the staff type belonging to this instrument type; 0 = pitched; 1 =
percussion; 2 = tablature (read only).
ChromaticTransposition
Returns the number of half-steps (semitones) describing the transposition of transposing instruments; such as for
B-flat Clarinet, this returns -2 (read/write).
ChromaticTranspositionInScore
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,
for example, 12 for piccolo or –12 for guitars (read only).
ComfortableRangeHigh
Returns the highest comfortable note (MIDI pitch) of the instrument (read only).
ComfortableRangeLow
Returns the lowest comfortable note (MIDI pitch) of the instrument (read only).
ConcertClefStyleId
Returns the style ID of the normal clef style of the instrument (read only).
DefaultSoundId
Returns the default sound ID used by the instrument (read only).
DiatonicTransposition
Returns the number of diatonic steps describing the transposition of transposing instruments; such as for B-flat
Clarinet, this returns -1 (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
FullName
Returns the name of the instrument as visible on systems showing full instrument names (read only).
Chapter 4: Object Reference89
Instruments dialog in Sibelius (read/write).
HasBracket
Returns True if the instrument has a bracket (read only).
HasKeySignatureOrTuning
Returns True if the instrument type has the Key signature / Tuning checkbox switched 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, that is corresponding to the Tab instrument to use for string tunings in the New/Edit Instrument
dialogs.
IsVocal
Returns True if the instrument type used has the Vocal staff option switched on, meaning that, for example, 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).
NumStrings
Returns the number of strings in a tablature staff (read only).
OtherClefStyleId
Returns the style ID of the clef style of the second staff of grand staff instruments, piano for example (read only).
Pan
Returns the instrument’s default pan setting, in the range –127 (hard left) to 127 (hard right) (read only).
ProfessionalRangeHigh
Returns the highest playable note (MIDI pitch) of the instrument for a professional player (read only).
ProfessionalRangeLow
Returns the lowest playable note (MIDI pitch) of the instrument for a professional player (read only).
ShortName
Returns the name of the instrument as visible on systems showing short instrument names (read only).
StyleId
Returns the style ID of the instrument; see “Global Constants” on page 156 (read only).
TransposingClefStyleId
Returns the style ID of the clef to be used when Notes > Transposing Score is switched on (read only).
Chapter 4: Object Reference90
KeySignature
Derived from a BarObject.
Methods
None.
Variables
AsText
The name of the key signature as a string (read only).
IsOneStaffOnly
True if this key signature belongs to one staff only (read only).
Major
True if this key signature is a major key (read only).
Sharps
The number of sharps (positive) or flats (negative) in this key signature (read only).
Line
Anything you can create from the Create > Line dialog is a Line object, such as CrescendoLine, DiminuendoLine, and so on. These objects are derived from a BarObject.
Methods
None.
Variables
Duration
The total duration of the line, in 1/256th quarters (read/write).
EndBarNumber
The bar number in which the line ends (read only).
EndPosition
The position within the final bar at which the line ends (read only).
Chapter 4: Object Reference91
RhDx
The horizontal graphic offset of the right-hand side of the line, in units of 1/32 spaces (read/write).
RhDy
The vertical graphic offset of the right-hand side of the line from the center staff line, in units of 1/32 spaces, positive going upwards (read/write).
StyleId
The identifier of the line style associated with this line (read only).
StyleAsText
The name of the line style associated with this line (read only).
LyricItem
Derived from a BarObject
Methods
None.
Variables
The total duration of the lyric line, in 1/256th quarters (see “Line” on page 91) (read/write).
NumNotes
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 variable to the correct length.
StyleAsText
The text style name (read/write).
StyleId
he identifier of the text style of this lyric (read/write).
SyllableType
An integer indicating whether the lyric is the end of a word (EndOfWord) or the start or middle of one (Mid-
dleOfWord) (read/write). This affects how the lyric is jusitifed, and the appearance of hyphens that follow it.
EndOfWord and MiddleOfWord are global constants; see “SyllableTypes for LyricItems” on page 193.
Text
The text as a string (read/write).
Chapter 4: Object Reference92
NoteRest
Derived from a BarObject.ANoteRest contains Note objects, stored in order of increasing diatonic pitch.
for each variable in returns the notes in the NoteRest.
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 True 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. If force stem dir is set to True (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, that is 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 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 Note Input page of File
> Preferences). Returns the Note object created (to get the NoteRest containing the note, use
Note.ParentNoteRest).
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 Add-
Adds a note with the given MIDI pitch (60 = middle C), for example 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, which is 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 File > Preferences). Returns the
Note object created.
Delete()
Deletes all the notes in the NoteRest, converting the entire chord into a rest of similar duration.
Chapter 4: Object Reference93
FlipStem()
Flips the stem of this NoteRest—this acts as a toggle.
GetArticulation(articulation number)
Returns True or False depending on whether the given articulation is currently set on this note. The valid articulation numbers are defined in “Articulations” on page 192.
NoteRest[array element]
Returns the nth note in the chord, in order of increasing diatonic pitch (counting from 0). For example,
NoteRest[0] returns the lowest note (in terms of diatonic pitch–see AddNote below).
RemoveNote(note)
Removes the specified Note object.
SetArticulation(articulation number,set)
If set is True, turns on the given articulation; otherwise turns it off. The valid articulation numbers are defined
in “Articulations” on page 192.
Transpose(degree, interval type[
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 156. 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
the Sibelius.CalculateInterval and Sibelius.CalculateDegree methods.
,keep double accs])
Variables
ArpeggioDx
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).
ArpeggioType
The type of note-attached arpeggio line present on the NoteRest. Values are ArpeggioTypeNone, Arpeg-