How it Works
Pinnacle Systems
Loading...
P
S
T
Loading...
Loading...
Sibelius - 8.6
User Manual
180 pgs883.6 Kb0
Table of contents
Loading...

Pinnacle Systems Sibelius - 8.6 User Manual

Sibelius® Software
Using the ManuScript Language
Legal Notices
© 2017 Avid Technology, Inc., (“Avid”), all rights reserved. This guide may not be duplicated in whole or in part without the written consent of Avid.
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 non­U.S. patents. Details are available at www.avid.com/patents.
Product features, specifications, system requirements, and availability are subject to change without notice.
Guide Part Number 9329-65847-00REV A 5/17

Contents

Chapter 1. Introduction ........................................................ 1
Rationale ............................................................. 1
Technical Support ...................................................... 2
System Requirements and Compatibility Information ........................... 2
Conventions Used in Sibelius Documentation ................................. 3
Chapter 2. Sibelius ManuScript Language Tutorial ................................. 5
Edit Plug-ins ........................................................... 5
Editing the Code........................................................ 9
Chapter 3. Reference ......................................................... 12
Syntax .............................................................. 12
Expressions .......................................................... 14
Operators ............................................................ 16
Chapter 4. Object Reference ................................................... 18
Hierarchy of Objects.................................................... 18
All Objects ........................................................... 19
Accessibility .......................................................... 21
Bar................................................................. 21
Barline .............................................................. 30
Barlines ............................................................. 30
BarObject ............................................................ 31
BarRest ............................................................. 36
Bracket .............................................................. 36
Clef................................................................. 37
Comment ............................................................ 38
ComponentList ........................................................ 39
Component........................................................... 39
DateTime ............................................................ 40
Dictionary ............................................................ 41
Sibelius ManuScript Language Guide iii
DocumentSetup ....................................................... 42
DynamicPartCollection.................................................. 45
DynamicPart.......................................................... 46
EngravingRules ....................................................... 47
File ................................................................. 50
Folder ............................................................... 51
GuitarFrame .......................................................... 52
GuitarScaleDiagram.................................................... 56
HitPointList ........................................................... 57
HitPoint.............................................................. 58
InstrumentChange ..................................................... 58
InstrumentTypeList..................................................... 59
InstrumentType ....................................................... 59
KeySignature ......................................................... 62
Line ................................................................ 62
LyricItem............................................................. 63
NoteRest ............................................................ 64
Note ................................................................ 68
NoteSpacingRule ...................................................... 72
PageNumberChange ................................................... 74
PluginList ............................................................ 76
Plugin ............................................................... 76
RehearsalMark........................................................ 77
Score ............................................................... 77
Selection ............................................................ 88
Sibelius.............................................................. 92
SoundInfo........................................................... 103
SparseArray ......................................................... 104
SpecialBarline ....................................................... 106
Staff ............................................................... 106
Syllabifier ........................................................... 111
SymbolItem and SystemSymbolItem ...................................... 112
SystemObjectPositions ................................................ 112
SystemStaff, Staff, Selection, Bar and, all BarObject-derived Objects ............ 113
SystemStaff ......................................................... 113
Contentsiv
Text and SystemTextItem .............................................. 114
TimeSignature ....................................................... 115
TreeNode ........................................................... 116
Tuplet .............................................................. 116
Utils ............................................................... 118
VersionHistory ....................................................... 124
Version ............................................................. 124
VersionComment ..................................................... 125
Chapter 5. Global Constants .................................................. 127
Global Constants ..................................................... 127
Contents v
Contentsvi

Chapter 1: Introduction

ManuScript is a simple, music-based programming language invented by Ben Sloman to write plug-ins for Si­belius. 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 some­times found in Victorian novels.) For more information on Simkin, and additional help on the language and syn­tax, 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 no­tation 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-spe­cialist 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 recompi­lation. 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: Introduction 1
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/mail­man/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 third­party 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:
:
Convention Action
File > Save Choose Save from the File tab
Control+N Hold down the Control key and press the N key
Control-click Hold down the Control key and click the mouse but-
ton
Right-click Click 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: Introduction 3
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.
2 Choose File > Plug-ins > Edit Plug-ins. The following dialog appears:
Chapter 2: Sibelius ManuScript Language Tutorial 5
3 Click New.
4 You are asked to type the internal name of your plug-in (used as the plug-in’s filename), the name that should
appear on the menu and the name of the category in which the plug-in should appear, which will determine which ribbon tab it appears on.
The reason for having two separate names for plug-ins is that filenames may be no longer than 31 characters on Macs running Mac OS 9 (which is only significant if you intend your plug-in to be used with versions of Sibelius prior to Sibelius 4), but the menu names can be as long as you like.
5 Type Test as the internal name, Test plug-in as the menu name and Tests as the category name, then click OK.
6 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.
7 If you look in the Home > Plug-ins gallery again you’ll see a Tests category, with a Test plug-in underneath it.
8 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.
9 Click OK on the dialog and the plug-in stops.
Chapter 2: Sibelius ManuScript Language Tutorial 6
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:
t and click Edit (or simply double-click the plug-in’s name to edit it). You’ll see a dialog
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.
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:
Chapter 2: Sibelius ManuScript Language Tutorial 7
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 words, when you choose
Home > Plug-ins > Tests > Test, the plug-in’s Run method is called. If you write any
main() in C/C++ and Java). In other
other methods, you have to call them from the Run method—otherwise how can they ever do anything?
Click on
Run, then click Edit (or you can just double-click Run to edit it). This shows a dialog where you can edit
the Run method:
In the top field you can edit the name; in the next field you can edit the parameters (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. No­tice that the method name is followed by a list of parameters in parentheses. In this case there’s only one param­eter: 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 Si-
belius program; the statement is telling Sibelius to pop up the message box (C++ and Java programmers will rec­ognize that this variable refers to an “object”). If this hurts your brain, we’ll go into it later.
Chapter 2: Sibelius ManuScript Language Tutorial 8

Editing the Code

Now try amending the code slightly. You can edit the code just like in a word processor, using the mouse and ar­row 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);
You can check this makes sense (or, at least, some kind of sense) by clicking the Check Syntax button. If there are any blatant mistakes (e.g. missing semicolons) you will be notified where they are.
X/C/V for cut, copy and paste respectively. If you right-click
Then close the dialogs by clicking and a message box with the answer
How does it work? The first two lines should be obvious. The last line uses & to stick two strings together. You cannot use swer!).
One pitfall: try changing the second line to:
+ as this works only for numbers (if you try it in the example above, you will get an interesting an-
OK, OK again then Close. Run your amended plug-in from the Plug-ins menu
1+1=2should appear.
x += 1;
Then click Check syntax. You will encounter an error: this syntax (and the syntax x++) is allowed in various languages but not in ManuScript. You have to do
x = x+1;.
Where Plug-ins are Stored
Plug-ins supplied with Sibelius are stored in folders buried deep within the Sibelius program folder on Windows, and inside the application package (or “bundle”) on Mac. It is not intended that end users should add extra plug­ins to these locations themselves, as we have provided a per-user location for plug-ins to be installed instead. When you create a new plug-in or edit an existing one, the new or modified plug-in will be saved into the per­user location (rather than modifying or adding to the plug-ins in the program folder or bundle):
• On Windows, additional plug-ins are stored at C:\Users\username\AppData\Roaming\Avid\Sibelius\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.)
Chapter 2: Sibelius ManuScript Language Tutorial 9
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 state­ment on several lines.
You can add comments to your program, again like C/C++ and Java. Anything after the line. Anything between
/* and */ is ignored, whether just part of a line or several lines:
// is ignored to the end of
// comment lasts to the end of the line /* you can put several lines of comments here */
For instance:
Sibelius.MessageBox("Hi!"); // print the active score
or:
Sibelius /* this contains the application */ .Message­Box("Hi!");
Variables
x in the Test plug-in is a variable. In ManuScript a variable can be any sequence of letters, digits or _ (under-
score), 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 dia­log 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 ac­cessed 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, Manu­Script strings uses the back-slash gle quote character in your strings, use clude the backslash itself in a ManuScript string one has to write
Chapter 2: Sibelius ManuScript Language Tutorial 10
\ as an “escape character” to represent certain special things. To include a sin-
\', and to include a new line you should use \n. Because of this, to in-
\\.
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 in­stead (as in the first call to 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'
MessageBox above) the number is converted to text. If you give it an object (such
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 Tutorial 11

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: Reference 12
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 state­ments 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 sub­object is possible you can specify the type:
for each Type variable in expression
block
for example:
for each NoteRest n in thisstaff {
n.AddNote(60); // add middle C
}
Chapter 3: Reference 13
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:
for x=1 to note.NoteCount {
...
}
works correctly.
variable = expression;
for example:
value = value + 1;
or
variable.variable = expression;
for example:
Question.CurrentAnswer=True;
variable.identifier(comma-separated expressions);
for example:
thisbar.AddText(0,"Mozart","text.system.composer");
identifier(comma-separated expressions);
Calls a method in this plug-in, for example:
CheckIntervals();
return expression;
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
null This is a literal object meaning “nothing.”
Identifier
member variable
Chapter 3: Reference 14
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\ Baselineadjustment:usenormal,sub(forsubscript)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:
Title, Composer, Arranger, Lyricist, MoreInfo, Artist, Copy-
, Publisher and PartName.
right
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: Reference 15
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 con­ditions such as
a = b equals (for numbers, text or objects) a < b less than (for numbers) a > b greater than (for numbers) c and d both are true c or d either are true not c inverts 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: Reference 16
= and <. The available conditions are very simple:
less than or equal to
Arithmetic
a + b add a - b subtract a * b multiply a / b divide a % b remainder
-a negate (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: Reference 17

Chapter 4: Object Reference

Hierarchy of Objects

Sibelius object
Score
VersionHistory
Version
VersionComment
DynamicPartCollection
EngravingRules
DynamicPart
NoteSpacingRule
Stave (including the SystemStave)Selection
Bar
Text, Clef, Line, TimeSignature, KeySignature,
Highlight, Lyric, Barline, Tuplet, GuitarFrame,
GuitarScaleDiagram, Comment,
NoteRest (these are all BarObjects)
Note (in NoteRests only)
Chapter 4: Object Reference 18

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 Reference 19
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 de­fault 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.
s=':a:b:c'; bits=SplitString(s,':', false); // bits[0] = ''; bits[1] = 'a'; bits[2] = 'b' ... s='a b c'; bits=SplitString(s,' ', true); // bits[0] = 'a'; bits[1]='b' ...
StopPlugin([message])
Stops the plug-in, and shows the optional message in an alert box. Opens the plug-in editor at the line of code reached.
Substring(expression,start,[length])
This returns a substring of the expression starting from the given start position (zero-based) up to the end of the expression, 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 (zero­based) 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
Chapter 4: Object Reference 20
's a trace");
ValidationChecking(enable[, object1[, object2]...])
If enable is the only parameter, validation checking is enabled for all types of objects, and across all plug-ins. If you supply one or more object parameters (such as Tuplet, Score, BarObject, and so on), only those ob­jects 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 127. The optional extra_text parameter takes a string that will be added after the nu­meric 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 cre­ated.
Chapter 4: Object Reference 21
AddChordSymbolFromPitches(position,pitches[,instrument style])
Adds a chord symbol from the given array of pitches at the specified position. The optional instrument style pa­rameter 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.
AddClef(pos,concert pitch clef[,transposed pitch clef])
Adds a clef to the staff at the specified position. concert pitch clef determines the clef style when Notes > Trans­posing 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 135. 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 min­imized (if not specified, the comment is created maximized by default). If you want to specify the maximized pa­rameter without specifying a particular color, set color to -1.
AddCommentWithName(sr,text,username[,color[,maximized]])
Adds a comment that will display a given username at the specified sr position in the current bar, displaying the specified text. The optional color parameter allows you to specify the color of the comment that is created (if not specified, the comment is created with its default color), and the optional maximized Boolean parameter allows you to set the comment to be minimized (if not specified, the comment is created maximized by default). If you want to specify the maximized parameter without 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 dis­place 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, oth­erwise 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 centre. You may specify the size of the graphic by specifying a value for size ratio. This defaults to 1.0, which has the same effect as creating a graphic in Sibelius manually using Create > Graphic. (As with AddGraphic, 0.5 would halve its size, and 2.0 double it.) The graphic may be rescaled to a maximum of five times its intial size. This function returns True if successful, otherwise False.
Chapter 4: Object Reference 22
AddGuitarFrame(position,chord name[,instrument style[,fingerings])
Adds a chord symbol for the given chord name to the bar. The optional instrument style parameter should refer to an existing instrument type that uses tab, and should be specified by identifier; see “Instrument Types” on page 136. 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.
AddInstrumentChange(pos,styleID[,add_clef[,show_text[,text_label[,show_warning[,warning_la­bel, [full_instrument_name[, short_instrument_name]]]]]])
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 136 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 param­eter; 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 instru­ment 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 omited), the instrument names will remain unchanged. Returns the Instru­mentChange object created.
AddKeySignatureFromText(pos,key name,major key[,add double barline[,hidden[,one staff only]]])
Adds a key signature to the bar. The key signature is specified by text name, such as “Cb” or “C#”. The third pa­rameter 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
AddKeySignature(pos,num
flag. Returns the key signature object created.
sharps,major key[,add double barline[,hidden[,one staff only]]])
Adds a key signature to the bar. The key signature is specified by number of sharps (+1 to +7), flats (–1 to –7), no accidentals (0) or atonal (-8). The third parameter is a Boolean flag indicating if the key is major (or minor). Unless the fourth parameter is set to False, a double barline will ordinarily be created alongside the key signa­ture 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 key signature object created.
Chapter 4: Object Reference 23
AddLine(pos,duration,line style[,dx[,dy[,voicenumber[,hidden]]]])
Adds a line to the bar. The line style can be an identifier such as “line.staff.hairpin.crescendo” or a name, such as “Crescendo”. For a complete list of line style identifiers that can be used in any Sibelius score, see “Line Styles” on page 131. Style identifiers are to be preferred to named line styles as they will work across all lan­guage 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 cre­ated.
AddNote(pos,sounding pitch,duration,[tied [,voice[,diatonic pitch[,string number]]]])
Adds a note to staff, adding to an existing NoteRest if already at this position (in which case the duration is ig­nored); 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 cal­culated 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 bar object is followed by one or more blank pages, each blank page may also have a page number change of its own. If unspecified, the page number change will be created on the next available page (whether it contains music or not) after the bar, otherwise the user may specify a 1-based offset which refers to the nth blank page after the bar itself.
Chapter 4: Object Reference 24
Loading...
+ 150 hidden pages
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use