IncludeOnce(string file)

Include file only and only if it hasn't been included before.

For that, you must always use IncludeOnce instead of Include. Include is safe and fast for simple script that create constants and functions, but may load the CPU if included file performs heavy tasks.

Usage

IncludeOnce("SMJavaCollections")

throw(string exception)

Log (console and/or file) and stop the script with error().

Inspired from Java's throw new Exception(...) but without 'catch' mechanism in Lua.

See

err

assertNumber(n, string errorMessage)

Assert n is a not-nil number, else throw errorMessage.

See

assertPositiveNumber

assertNegativeNumber

assertNotZero

assertPositiveNumber(n, string errorMessage)

Assert n is a positive number, else throw errorMessage.

See

assertNumber

assertNegativeNumber

assertNotZero

assertNegativeNumber(n, string errorMessage)

Assert n is a negative number, else throw errorMessage.

See

assertNumber

assertPositiveNumber

assertNotZero

assertNotZero(n, string errorMessage)

Assert n is a number but not 0, else throw errorMessage.

See

assertNumber

assertPositiveNumber

assertNegativeNumber

assertString(s, string errorMessage)

Assert s is a not-nil string (possibly empty), else throw errorMessage.

See

assertNotEmptyString

assertNotEmptyString(s, string errorMessage)

Assert s is a not-nil and not empty string, else throw errorMessage.

See

assertString

assertTrue(b, string errorMessage)

Assert b is true, else throw errorMessage.

See

assertFalse

assertNotNil

assertExpression

assertFalse(b, string errorMessage)

Assert b is false, else throw errorMessage.

Note: if you check a expression, e.g. x < y, Lua returns nil if the comparaison fails, instead of false.

See

assertTrue

assertNil

assertExpression

assertTable(t, string errorMessage)

Assert t is a table, else throw errorMessage.

assertFunction(f, string errorMessage)

Assert f is a function, else throw errorMessage.

assertNil(n, string errorMessage)

Assert n is nil, else throw errorMessage.

See

assertNotNil

assertFalse

assertExpression

assertNotNil(n, string errorMessage)

Assert n is not nil, else throw errorMessage.

See

assertNil

assertTrue

assertExpression

assertExpression(expr, string errorMessage)

Assert an expression result is true.

This is the equivalent of Lua assert function with more logging.

See

assertTrue

assertNotNil

assertEquals(expr, expected, string Text)

Assertion an expression or function call equals an expected result.

This is useful for unit tests.

Error

If expr ~= expected

assertDialog(dialog, string errorMessage)

Assert dialog is a Dialog, else throw errorMessage.

assertScore(s, string errorMessage)

Assert s is a Score, else throw errorMessage.

assertType(t, string expectedType, string errorMessage)

Assert type(t) is a expectedType, else throw errorMessage.

See

assertDialog

assertFunction

assertNumber

assertScore

assertString

assertTable

Example

assertType(s, "Staff", "MyFunction, argument #1")
--> if s is not a Staff, this print
--> ERROR MyFunction, argument #1, expected Staff, got ...

CompareMyrScriptVersion(string version)

Is MyrScript =, < or > version x.y.z?

As Application.MyrScriptVersion is a string, comparison may fail in the future, "10.1.1" is greater than "9.9.9" but string comparison will stay it's lower (because "1" < "9").

Return

string: "<", ">" or "=" if version is lower, greater or equal to MyrScript version.

CompareVersions(string a, string b)

Compare two version numbers in x.y.z string format.

Return

string: "<", ">" or "=" if a is lower, greater or equal to b.

Example

CompareVersions("9.9.7", "9.9.6") --> ">"

PlayFromBar(Score score, int barNumber, bool showKaraoke, bool scrollMusic, bool followMusic, int metronomeBars)

Start playing music from specified bar.

Target.PlayMusic() is bogus; here is a work-around.

Usage

PlayFromBar(FrontScore(), 2)

DeleteAllTargets(Score score, bool preserveScore)

Delete all targets from a score.

SortTargets(Score score)

Sort the targets by bar number.

Targets may be sorted by creation date in your score, if the last inserted is B between A and C, order is A, C, B. Thiis function sorts by deleting and recreating targets as A, B, C.

Return

bool: false if no sort was needed, true if sort was done.

Usage

SortTargets(FrontScore())

switch(term, table cases)

switch..case.

Keyword switch doesn't exist in Lua? Here it is. Each case can test more things than C-like equals: equals, not equals, comparison (greater, lower), in a table, between two values (range). See SwitchCaseTest() for examples. Note that it creates tables, so switch is not best solution in huge loops where a set of if..elseif..elseif..end can do the job faster.

Return

a value if cases' "body" functions return a value.

Usage

switch(term, { case(...), case(...), default(...) }).

Example

local result = switch(my_number, {
case("<", 0, function(term) print(term.." is negative") return "negative" end),
case("eq", 2, function(term) print(term.." = two") return "=2" end, false),
case("in", {3,5,7,11,13,17}, function(term) print(term.." is a prime") return "prime" end),
case("range", {20,29}, function(term) print("20 <= "..term.." <= 29") return "between 20 and 29" end),
default( function(term) print(term.." doesn't match any case, this is default") return "The answer is... 42" end)
})

case(string _type, _params, function _func, bool _break)

Create a case for switch() function.

Return

table: a case for switch() function

See

switch

default(function _func)

Create a default case for switch() function.

Return

table: a case for switch() function

See

switch

CopyFXProcessor(FXProcessor source, FXProcessor dest)

Copy all parameters from a FXProcessor to another one.

Error

if source or dest are nil

SetInstrumentFXProcessor(Instrument instr, FXProcessor fxproc)

Set the default FX Processor for an instrument.

The instrument's FXProcessor is not visible on the score. It's the one you edit from the instrument dialog's "FX" button.

PlayNote(Symbol symbol)

Plays a note, shortcut and fix for Staff.PlayNotes().

Play only one note (the symbol parameter), in its context (tempo at its Time position), duration, velocity and pitch.
Fix the no-sound bug when pitch==0 on grid drum staves

SetDrumGridsDivision(Score score, int numberOfDivisions)

Set the Staff.DefaultDrumDivision to all drum grid-staves.

Error

if score is nil or numberOfDivisions < 1

round(number num, int numberOfDecimals)

Round a number.

Return

number: the rounded number, i.e. floor(number + 0.5) for an integer (no decimals)

duration_note_to_ms(int noteDuration, number tempo)

Convert a note duration to milliseconds, according to tempo.

Return

number: Rounded to 3 decimals

Error

if noteDuration is nil, if tempo is nil or <= 0

duration_ms_to_note(number milliseconds, number tempo)

Convert a duration in milliseconds to a note duration according to tempo.

Return

int: A note duration, comparable to DURATION_QUARTER and other constants in MSDefine

Error

if milliseconds is nil, or tempo is nil or <= 0

duration_percent_of_note_to_ms(int percent, int noteDuration, number tempo)

Convert a percentage of note duration to milliseconds, according to tempo.

Return

number: Rounded to 3 decimals

Error

if percent is nil, if noteDuration is nil, if tempo is nil or <= 0

duration_ms_to_percent_of_note(number milliseconds, int noteDuration, number tempo)

Convert a duration in milliseconds to a percentage of a note duration, according to tempo.

Return

int: Percent of noteDuration

Error

if milliseconds is nil, if noteDuration is nil, if tempo is nil or <= 0

duration_256th_of_quarter_to_ms(int nbOf256th, number tempo)

Convert 256ths of quarter to milliseconds, according to tempo.

Return

number: Rounded to 3 decimals

Error

if nbOf256th is nil, if tempo is nil or <= 0

duration_ms_to_256th_of_quarter(number milliseconds, int noteDuration, number tempo)

Convert at duration in milliseconds to 256th of quarter, according to tempo

Return

int: 256th of quarter

Error

if milliseconds is nil, if noteDuration is nil, if tempo is nil or <= 0

duration_256th_of_quarter_to_percent_of_note(int nbOf256th, int noteDuration, number tempo)

Convert 256ths of quarter to a percentage of a note duration, according to tempo.

Return

int:

Error

if nbOf256th is nil, if noteDuration is nil, if tempo is nil or <= 0

duration_percent_of_note_to_256th_of_quarter(int nbOf256th, int noteDuration, number tempo)

Convert a percentage of a note duration to 256ths of quarter, according to tempo.

Return

int:

Error

if nbOf256th is nil, if noteDuration is nil, if tempo is nil or <= 0

GetTempoAtTime(Score score, int time)

Get tempo value and its Dynamic object (if applicable) at specified time of the score

Returns

number: Tempo value (floatting point number)

int: Reference note length, DURATION_QUARTER for general tempo

Dynamic: nil if no tempo was added to the score, i.e. the returned value is general tempo

Error

if score is nil

GetStavesGroup(Score score, Staff staff)

Get the StavesGroup of a Staff, or nil if staff is not grouped.

Return

StavesGroup: nil if staff is not grouped

Error

if score is nil or staff is nil

GetDynamicsThatApplyToStaff(Score score, Staff staff)

Get all Dynamic that apply to the specified staff.

Dynamics are:

• velocity changes (crescendo, descrendo, pppp to fff)
• Tempo change
• Pedal on/off
• Ottava

Return

Collection: of Dynamics that apply to staff are on attached to it, or one of merged staves with it, or one of the staves of the contain group, or to the whole score.

Error

if score or staff are nil

See

DYNAMIC_* constants in MSDefine

Dynamic.Type

DynamicIsTempo(Dynamic dynamic)

Is dynamic a Tempo?

Return

bool: true if dynamic.Type==DYNAMIC_TEMPO

DynamicIsOttava(Dynamic dynamic)

Is dynamic an ottava (8va, 8vb, 15va or 15vb)?

Return

bool: true if dynamic is 8va, 8vb, 15va or 15vb

DynamicIsPedal(Dynamic dynamic)

Is dynamic an pedal (Ped.

or *)?

Return

bool: true if dynamic is Ped. or *

DynamicIsVelocity(Dynamic dynamic)

Is dynamic a velocity (power) change?

Return

bool: true if dynamic is crescendo, decrescendo, ppp to fff... i.e. not a pedal, not a tempo, not a ottava

SMPitchToString(int pitch, int preferredAccidental, int compatible, string preferredNote)

Extension and bugfix for builtin PitchToString function.

• Allow pitches out of 0..127 bounds, but keep in mind that HA can't handle them!
• PitchToString(11) gives 11, SMPitchToString(11) returns B-1

Returns

string: Anglo-saxon note name followed by octave, e.g. "Ab5".

int: Accidental for the note, one of MSDefine NATURAL,FLAT,SHARP,DOUBLE_FLAT,DOUBLE_SHARP constants.

SMStringToPitch(string name)

Extension and bugfix for builtin StringToPitch function.

• Allow pitches out of 0..127 bounds
• StringToPitch("B-1") gives the strange 71 result, SMStringToPitch("B-1") returns 11
• Handles double-sharp (## or x) and double-flat (bb)

Return

int: May be out of 0..127 range.

GetChordsFromStaff(Score score, Staff staff, bool held)

Get the chords of a staff from the chord line and return detailed informations.

This is useful to build bass and chords accompaniments, perform analysis, or whatever you want. The returned structure is a table, indexed from 1 to number of chords. Each element is a

• Chord: a Chord object, able to understand more complex notations than HA. From this object, you can obtain the list of notes, chord octave, bass octave (2 octaves lower), inversion...
• BarNumber: the bar number where the chord is writed
• TimeBegin: time (in tick, from the beginning of the score), where the chord starts to play
• TimeEnd: time (in ticks, from the beginning of the score), where the chord ends, juste before next chord or an empty cell/bar.
• ArppegioDelay: by default, staff.ChordArpeggioDelay. May change if [Annn] command has been encountered in chord line.

Return

table:

See

Chord for more details about Chord object.

Example

local chords = GetChordsFromStaff(FrontScore(), FrontScore().FirstStaff)
for i=1,getn(chords) do
print("Chord #" .. i .. ": "..chords[i].Chord:toASCIIName())
print("Bar #" .. chords[i].BarNumber)
print(tdebug(chords[i].Chord:notes()))
end

RGBSelectColor()

Workaround for Application.RGBSelectColor which returns "000000" (black) instead of choosen color in global preferences.

Return

string: