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

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

Assertion an expression or function call equals an expected result; if both are string, the cases are ignored.

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 <strlower(expr) ~= strlower(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.

expr can be a number, an expression or a string. This a convenient way to ensure that the result of an expression is never nil where it may cause troubles or unknown behaviour: myDialogItem.IsVisible = bool(a_long_expression) is a syntaxic sugar for myDialogItem.IsVisible = (a_long_expression) or false

Return

boolean: true if expr == true or expr == "1", false otherwise.

Example

 print(bool(nil)) --> 0
 print(bool(3)) --> 0
 print(bool("hello")) --> 0
 print(bool(1 == 3)) --> 0
 print(bool(3 < 7)) --> 1
 print(bool("1")) --> 1

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

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

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.

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

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, not convenient for deletion. It can skips ghost rests and special symbols, handles individual and continuous (range) selection.

Return

int: Number of processed symbols

Error

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

See

SMApplyToAllSymbols

SMApplyToAllSymbols(Score score, staves, int firstBar, int lastBar, function processFunc, boolean excludeSpecials)

Apply a function to all symbols in the score, or staff, or in a range of 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.

Does not handle microtonal accidentals.

• 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, boolean multiple)

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

Return

• A table if multiple = true,
• A string if multiple = false and the setting is found,
• nil if multiple = false and no setting is found.

Example

 local tab = GetGlobalSetting("tabPredefNuances", true)
 --> {"tabPredefNuances 0 20", "tabPredefNuances 1 40", ...}
 local ppp = GetGlobalSetting("tabPredefNuances 0") --> 20
 local pp = GetGlobalSetting("tabPredefNuances 1") --> 40

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

SMEnterString(string text, string defaultValue)

Call to EnterString with accessibility and assertions checks

Return

string: The entered text or nil if user canceled.

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

ChooseNoteHeadShape(int defaultValue)

Open a dialog to choose a note head shape.

Return

int: One of SHAPE_* constants, or nil if user cancelled the choice.

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

IsThemeSoundsActive()

Are interface sounds active in scripts using SMDialog and SMMenu?

To set up screen reader, go to Scripts > Miscellaneous > Swiss knife menu, then Settings > Interface sounds.

Return

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

PlayThemeSound(string soundName, boolean wait)

Play a "theme" sound, if set to active.

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.

To set up screen reader, go to Scripts > Miscellaneous > Swiss knife menu, then Settings > Accessibility.

Return

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

See

ScreenReader

MuteScreenReader(int delay)

Temporarily mute the Screen Reader for a short delay.

It may be useful, for optimization concerns, if next coming actions will call ScreenReader(...) multiple times in a very short delay.
If ScreenReader is not set up to active, then this has no effect.

See

UnMuteScreenReader

UnMuteScreenReader()

After MuteScreenReader(...) and the massive actions that would have produced unaudible audio messages, unmute the Screen Reader.

If ScreenReader is not set up to active, then this has no effect.

See

MuteScreenReader

ScreenReader(string text, boolean wait)

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

Add accessibility to built-in Message() function.

The Message(...) display msg and requires user to click 'Ok' button or press Enter key. If a screen reader is set (Scripts > Misc. > Swiss knife menu > Settings), msg is said by the TTS. An optional argument allow only vocal message (skip the dialog) if screen reader is active.

MenuSingleChoice(string title, Lexicon lexicon, datas, string header, boolean hideRadios)

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.

See

https://www.myriad-online.com/cgi-bin/bbs/YaBB.pl?board=MYRSCRIPT;action=display;num=1760458849

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
    -- sd = STEM_AUTO, or STEM_UP, or STEM_DOWN
 else -- sd=nil, no selection, user canceled the choice
 end

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

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

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