int BAR_STATE_UNDEFINED

Bar visibility state: undefined: should not happen.

int BAR_STATE_VISIBLE

Bar visibility state: normal, visible.

int BAR_STATE_MULTI_FIRST

Bar visibility state: visible, first bar of a multi-rest or multi-repeat.

int BAR_STATE_MULTI_MIDDLE

Bar visibility state: not visible, inside (but not last bar of) a multi-rest or multi-repeat.

int BAR_STATE_MULTI_LAST

Bar visibility state: not visible, last bar of a multi-rest or multi-repeat.

int BAR_STATE_BEFORE_PRINT_REGION

Bar state visibility: not visible, before first printed bar

int BAR_STATE_AFTER_PRINT_REGION

Bar state visibility: not visible, after last printed bar

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("SMStructureReader")

throw(string exception, boolean visual, function catch)

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

Inspired from Java's throw new Exception(...) with a function as 'catch' mechanism.

See

err

assertNumber(n, string errorMessage, boolean visual)

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

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will stop with a console error message.

See

assertPositiveNumber

assertNegativeNumber

assertNotZero

assertPositiveNumber(n, string errorMessage, boolean visual)

Assert n is a positive number, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertNumber

assertNegativeNumber

assertNotZero

assertNegativeNumber(n, string errorMessage, boolean visual)

Assert n is a negative number, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertNumber

assertPositiveNumber

assertNotZero

assertNotZero(n, string errorMessage, boolean visual)

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

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertNumber

assertPositiveNumber

assertNegativeNumber

assertString(s, string errorMessage, boolean visual)

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

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertNotEmptyString

assertNotEmptyString(s, string errorMessage, boolean visual)

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

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertString

assertBoolean(b, string errorMessage, boolean visual)

Assert b is a boolean (true or false, not nil), else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertTrue

assertFalse

assertExpression

assertTrue(b, string errorMessage, boolean visual)

Assert b is true, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertFalse

assertNotNil

assertExpression

assertFalse(b, string errorMessage, boolean visual)

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.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertTrue

assertNil

assertExpression

assertTable(t, string errorMessage, boolean visual)

Assert t is a table, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertFunction(f, string errorMessage, boolean visual)

Assert f is a function, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertNil(n, string errorMessage, boolean visual)

Assert n is nil, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertNotNil

assertFalse

assertExpression

assertNotNil(n, string errorMessage, boolean visual)

Assert n is not nil, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertNil

assertTrue

assertExpression

assertExpression(expr, string errorMessage, boolean visual)

Assert an expression result is true.

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

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

See

assertTrue

assertNotNil

assertEquals(expr, expected, string Text, boolean visual)

Assertion an expression or function call equals an expected result.

This is useful for unit tests.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

Error

If expr ~= expected

assertInArray(value, table t, string text, boolean visual)

Assert a value is found in a table.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

Error

If value not found in t

assertDialog(dialog, string errorMessage, boolean visual)

Assert dialog is a Dialog, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertScore(s, string errorMessage, boolean visual)

Assert s is a Score, else throw errorMessage.

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

assertType(t, string expectedType, string errorMessage, boolean visual)

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

Return

boolean: true if assertion is correct, nil (for false) if it failed. If visual ~= true, no need to check the returned value, script will die with a console error.

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 ...

bool(expr)

Converts expr to a boolean.

Return

boolean: true if expr is true, false otherwise.

NOT(boolean b)

NOT function in boolean algebra.

Lua not x means "not nil", so not true is always true. NOT(true) returns nil (for false) so it can be used safely in if..then statements. If you want to obtain a real false, use the bool() function: a = bool(NOT(<expression>))

Return

boolean:

• true if b==nil or b==false
,
• nil (for false) otherwise.

AND(boolean ...)

AND function in boolean algebra, that accepts undefined number of arguments.

Arguments that are not booleans are considered as false: AND(true,"123") returns nil.

Return

boolean:

• true if all arguments are true
• nil (for false) if at least one argument is not true.

Error

if less than two arguments

OR(boolean ...)

OR function in boolean algebra, that accepts undefined number of arguments.

Arguments that are not booleans are ignored: OR("abc","123") returns nil

Return

boolean:

• true if at least one argument is true
• nil (for false) if no argument is true.

Error

if less than two arguments

NAND(boolean ...)

NAND (NOT AND) function in boolean algebra, that accepts undefined number of arguments and returns true if at least one argument is not true.

Arguments that are not booleans are considered as false: NAND(true,"123") returns true.

Return

boolean:

• true if at least one argument is not true,
• nil (for false) if all arguments are true.

Error

if less than two arguments

NOR(boolean ...)

NOR (NOT OR) function in boolean algebra, that accepts undefined number of arguments and returns true if all arguments are not true.

Arguments that are not booleans are considered as false: NOR("abc","123") returns true.

Return

boolean:

• true if all arguments are not true,
• nil (for false) if at least one argument is true.

Error

if less than two arguments

XOR(boolean a, boolean b)

XOR function in boolean algebra.

Return

boolean:

• true if only one of a and b is true,
• nil (for false) if a and b have same boolean value.

NIL(...)

Return true if all arguments are nil

Return

boolean:

• true if all arguments are nil,
• nil (for false) if at least one argument is not nil.

NOT_NIL(...)

Return true if all arguments are not nil

Return

boolean:

• true if all arguments are not nil,
• nil (for false) if at least one argument is nil.

IF(boolean expr, a, b)

Short and safe way to write ternary expression.

C-language: result = expr ? a : b;
Lua / MyrScript: result = expr == true and a or b
In a spreadsheet cell: =IF(expr;a;b) So here is Lua syntaxic sugar: result = IF(expr, a, b).

Return

a if expr is true, else b.

Error

if expr is not a boolean

IN(term, ...)

Check if term is in the list of following arguments.

Return

boolean: true if the list contains term, nil (for false) if the list doesn't contains term

See

ArrayContains

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 Application.MyrScriptVersion is lower, greater or equal to 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, boolean showKaraoke, boolean scrollMusic, boolean 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, boolean preserveScore)

Delete all targets (rehearsal marks) from a score.

Return

int: Number of deleted targets

SortTargets(Score score)

Sort the targets (rehearsal marks) 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

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

Usage

SortTargets(FrontScore())

isTable(obj)

Returns true if obj is a table or a MyrScript object represented as a table such as Score or Target.

Return

boolean: boolean

ArrayClear(table t)

Optimization of clearing a table.

tremove is time consuming because it shift all items after the removed one.
tremove from last to first would be a bit faster.
but setting items to nil is even faster.

ArrayContains(table tab, term)

Does tab contains term?

Return

boolean: true, or nil (for false)

Error

if tab's items are not comparable with term

gettagname(obj)

Return, if known, the tag name of an object.

When a tag is created and attached to a table by settag(myTable, tag(MyClass)), this method retrieves the MyClass name.

Return

string: The tag name, nil if not found.

Example

local c = Collection:new("string")
 print(gettagname(c)) --> "Collection"
 print(gettagname("Hello world")) --> "string"
 print(gettagname(FrontScore().FirstStaff)) --> Staff

IsLuaClass(string className)

Is className the name of a class?

Class is a table with a tag, and a :new(...) method.
Symbol, Staff or Score are not Lua class, Interval, Collection and SMDialog are.

Return

boolean: true if it's a class, nil for false if not.

Example

print(IsLuaClass("table")) --> nil
 print(IsLuaClass("Collection")) --> 1

tdebug(...)

Return the structure of a table, Collection or Map for debugging to the console.

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.

See

case

default

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, boolean _break)

Create a case for switch() function.

Return

table: a case for switch() function

See

switch

switch

default(function _func)

Create a default case for switch() function.

Return

table: a case for switch() function

See

switch

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.

SMApplyToAllSelectedSymbols(Score score, function processFunc)

Apply a function to all selected symbols, individually selected or continous selection.

MSLibrary's ApplyToAllSelectedSymbols(...) function doesn't handle individually selected symbols, and browse from last to first, which is safe for symbol deletion. This customized browse selected notes on all staves from first to last.

Return

int: Number of processed symbols

Error

if score is not a Score or processFunc is not a function.

See

SMApplyToAllSymbols

SMApplyToAllSymbols(Score score, Staff staff, int firstBar, int lastBar, function processFunc)

Apply a function to all symbols in the score, or staff, or in a rang eof bars.

Return

int: Number of processed symbols

Error

if arguments have wrong types.

See

SMApplyToAllSelectedSymbols

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)

NumberOfDecimals(number n)

Get the number of decimals of a number

Return

number: number

bound(number n, number mini, number maxi)

Ensure number n is within bounds [mini:maxi].

bound(n, mini, maxi) is a syntaxic sugar for max(min(n, maxi), mini)

Return

number: Bounded n.

dpi72_to_cm(number n)

Convert a 72 DPI pixel value into centimeters.

Return

number: number

cm_to_dpi72(number n)

Convert a centimeter value into 72 DPI pixels.

Return

number: number

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: 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: 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

GetDynamicsThatApplyToStaff(Score score, Staff staff)

Get all Dynamic that apply to the specified Staff.

Dynamics are:

• velocity changes (crescendo, decrescendo, 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 group, or to the whole score.

Error

if score or staff are nil

DynamicIsTempo(Dynamic dynamic)

Is dynamic a Tempo?

Return

boolean: true if dynamic.Type==DYNAMIC_TEMPO

DynamicIsOttava(Dynamic dynamic)

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

Return

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

DynamicIsPedal(Dynamic dynamic)

Is dynamic an pedal (Ped.

or *)?

Return

boolean: true if dynamic is Ped. or *

DynamicIsVelocity(Dynamic dynamic)

Is dynamic a velocity (power) change?

Return

boolean: 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)

Returns

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

int: Preferred accidental, one of AUTO, SHARP, FLAT... constants from MSDefine

GetChordsFromStaff(Score score, Staff staff, boolean 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 table which contains properties:

• Chord: a Chord object, able to parse 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, just 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: 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

GetGlobalSetting(string settingName)

Reads a line from global settings file, when MyrScript has no built-in function to get the value of a global setting.

Return

string: Found value, or nil if not found.

GetPreferredFont(string object)

Get preferred font from Global settings > Fonts

Returns

string: Font name, or nil if not found

int: Face, or nil if not found

int: Size, or nil if not found

string: color in RGB format, "000000" for now as it may be impossible to parse.

InstrumentIsUsed(Score score, Instrument instr, boolean excludeMutedStaves)

Is instr Instrument used in score ?

Instument.IsUsed returns true even if applide to rule that is never used, or used by a staff that has Virtual Singer voice active. This function handles these cases.

Return

boolean: boolean

EnterNumber(string text, number defaultValue, number minValue, number maxValue)

Ask the user to enter a number.

Use EnterString(...), and checks that the entered is a number within bounds. In case of error, ask again.

Return

number: or nil if user cancelled the choice.

EnterXY(string prompt, number minX, number maxX, number stepX, number factoryX, number currentX, number minY, number maxY, number stepY, number factoryY, number currentY, string displayValuesMask)

Ask to enter X,Y coordinates in a plotter with X and Y axis.

It's handy when you ask for 2 values, as X and Y offsets.

Returns

number: X, nil if user cancelled the dialog

number: Y, nil if user cancelled the dialog

Errors

if minX >= maxX or minY >= maxY

if factoryX or currentX are outside of [minX:maxX] range

if factoryY or currentY are outside of [minY:maxY] range

if factoryX and currentX, or factoryY and currentY are nil.

Example

 -- Create a new document with one staff, go to Page mode.
 -- This code moves first staff name position
 -- X between -50 and 50, Y between -30 and 30, steps are 1
 -- Negative Y go up, positive Y go down.
 -- Factory position is 0,0, current is 5,-24
   Include "SMUtils"
   x,y = EnterXY("Test XY",
    -50, 50, 1, 0, 5,
    -30, 30, 1, 0, -24,
    false, true, {FrontScore()},
    function(x,y,args)
      local staff = args[1].FirstStaff
      staff.TitleXOffset, staff.TitleYOffset = x, y
      Application.UpdateScores()
    end,
    "%x px, %y px" -- not mandatory, just show that unit is pixel (in 72 DPI)
  )

EnsureObjectInStaffArea(Score score, Staff staff, obj)

Ensure an object is in the Staff area, move it vertically if needed.

Return

boolean: true if object has been moved vertically, false otherwise.

CopyOrnaments(Symbol from, Symbol to)

Copy all ornaments from a Symbol to another one.

Returns

int: Number of copied ornaments

int: Number of copy errors

IsScreenReaderActive()

Is there a screen reader, a voice that assist visually impaired user?

The screen reader is set up by the script in Miscellaneous > Screen Reader setup. A call to ScreenReader("words to say") wil lsay nothing if not set up, or will say the words if a human voice is choosen.
If the words need time or resource to be build, you can optimize your code by calling IsScreenReaderActive() before this task.

Return

boolean: true if active, nil or false if not set up.

See

ScreenReader

ScreenReader(string text)

Say the text if text to speech is enable for visually impaired people (screen reader).

SMAlert(string msg)

Add accessibility to built-in Alert() function.

SMConfirmation(string msg)

Add accessibility to built-in Confirmation() function.

Return

boolean: The same result than Confirmation(msg)

SMMessage(string msg)

Add accessibility to built-in Message() function.

MenuSingleChoice(string title, Lexicon lexicon, datas)

Menu to pick one value in a list of items as radio buttons.

Return

choosen value (or caption), or nil if user canceled the choice.

Example

 local sd = MenuSingleChoice("Change stems direction", nil,
      {{"Auto", true, STEM_AUTO, "image:stemupdown.png"},
       {"Up", false, STEM_UP, "image:stemup.png"},
       {"Down", false, STEM_DOWN, "image:stemdown.png"}
      })
 if sd then -- change the stems direction of symbols
 else -- no selection, user canceled the choice
 end

MenuMultipleChoice(string title, Lexicon lexicon, datas, int minNbOfChoice, int maxNbOfChoice)

Menu to pick multiple value in a list of items as checkboxes.

For example, ChooseStaves(...) call it.

Return

table: Choosen values (or captions), or nil if user canceled the choice.

ChooseStaves(Score score, boolean multiple, boolean visibleOnly, function filterFunc, function selectFunc, int minNbOfChoice, int maxNbOfChoice)

Ask the user to choose one or multiple staves.

The builtin Score.UserChooseStaves(...) is a bit less flexible and not 100% browsable with keyboard. This custom version allow shortcuts, from 1 to 9 for 9 first staves, then the first available letter.

Here is what it looks like:

Return

table: Table of choosen staves, can be empty, or nil if user canceled the choice.

GetStavesGroups(Score score, Staff staff)

Get all StavesGroups of the score or containing staff if this argument is provided.

Return

table: An array of StavesGroups, ordered from first to last Staff (Score.FirstStavesGroup is the first created in the document, not the first printed). Array is empty if no StavesGroups found.

Error

if score is not a Score or staff is not a Staff

GetStavesInGroup(StavesGroup sg)

Return an array of staves in StavesGroup sg

Return

table: Array of Staff

StavesGroupName(StavesGroup sg)

Return the name (title) of sg or build a name from its first and last grouped staves.

Return

string: Unstyled string

Error

if sg is not a StavesGroup

ChooseStavesGroups(Score score, boolean multiple, boolean visibleOnly, function filterFunc, function selectFunc)

Ask the user to choose one or multiple staves groups.

Return

table: Array of choosen staves groups, can be empty, or nil if user canceled the choice.

AdjustStavesGroupSymbolPosition(Score score, table groups)

Experimental: Adjust horizontal and vertical staves group symbole (braces and brackets).

Return

int: Number of modified staves group symbols.

StaffSetAmbitus(Score score, Staff staff, boolean state)

Set the ambitus enabled or disabled for staff, and also at score's level else ambitus won't display.

ChooseView(Score score, boolean index, int (default=current)

Ask the user to choose one view, or a value for ViewIndex.

Return

int: view index

FontFaceNumberToString(int face)

Convert a font face (sum of FACE_* constants from MSDefine) to strings.

Returns

string: Long format string in English, e.g. "Bold, Italic"

string: Short format string, usable as well as number in SetStringStyle(...), e.g. "BI", but works better.
"" for no style (standard)

FontFaceStringToNumber(string str)

Convert a font face as string like "BI" into sum of FACE_* constants from MSDefine.

Return

int: Sum of FACE_* constants

ChooseFont(string object, table suggestedFonts, selected)

Ask the user to choose one font in a menu.

If available, the list starts by the font set in global settings > Fonts for object (e.g. "Tempo", "Staff name", see GetPreferredFont(..)),
then, a list of favorites fonts,
then, a list of suggested fonts (e.g. found in score).

Returns

string: Font name, nil if user canceled the choice.

int: Font face, sum of FACE_* constants in MSDefine

int: Size

string: RGB color

EnterFont(string font, face, number size, string color)

Ask the user to choose font, face, size and color using the built-in EditTextStyle() dialog.

Returns TextStyle properties instead of TextStyle object itself, as it is mandatory to dispose it, and often forgotten.

Returns

string: Font name, nil if user canceled the choice.

int: Font face, sum of FACE_* constants in MSDefine

int: Size

string: RGB color

ChooseColor(string object, table suggestedColors, selected)

Ask the user to choose one color in a menu.

If available, the list starts by a list of favorites colors, saved by previous choices for the same object (e.g. "Staff background").
Then, a list of suggested colors (e.g. found in score).
Then, the ability to pick a new color from the Color Picker, and save it to favorites for faster use next times.

Returns

string: Choosen color, in RRGGBB format, or nil if user canceled the choice.

string: Choosen color, in #RRGGBB format, or nil if user canceled the choice.

int: Color index, or nearest in 256 colors palette, or nil if user canceled the choice.