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

SMConfirmation(string msg)

Add accessibility to built-in Confirmation() function.

Return

boolean: The same result than Confirmation(msg)

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.

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.

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

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

Return

int: view index

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.

ChooseTarget(Score score, string prompt, int selectedBar, string selectedName)

Select a Target (rehearsal mark) in the Score.

Return

Target: Selected target or nil if user canceled the choice.

MidiGetEventFiltered(boolean allowNoteOn, boolean allowNoteOff, boolean allowCC, boolean allowProgramChange, boolean allowAftertouch, boolean allowPitchBend, boolean allowOthers, int delay, table allowedSources)

Apply a filter to Midi.GetEvent to exclude some Midi messages and return all events since last call.

You can exclude:

1. message you don't need, e.g. aftertouch
2. a lot of steps while moving a controller (slider, knob, pitch bend).
   To do this, set a delay in milliseconds. This result in a loss of data, note suitable for fine control of sound, but useful when hardware controllers replace mouse or computer keyboard inputs.

Return

table: Table of Midi events, each item are structured as:

• Event, int: type of event :
  • 1 mean note on (key pressed),
  • 2 mean note off or note on with velocity = 0 (key released)
  • 10 means polyphonic aftertouch
  • 11 means CC, Controller Change (modulation wheel, pedal, knobs, cursors, bank change...)
  • 12 means PC, Program Change
  • 13 means channel aftertouch
  • 14 means pitch bend
• Channel, int: the channel from 0 to 15
• Pitch, int: the note pitch / selected controller / program from 0 to 127
• Velocity, int: the velocity / controller value from 0 to 127
• TimeMs, int: the time position in millisecond of the event
• TimePos, number: the time position in the playing score (-1 if no score currently playing)
• Source, int: the source for this event (MSDefine constant):
  • INPUT_SOURCE_UNKNOWN: none/unknown
  • INPUT_SOURCE_MIDI: from an external MIDI device
  • INPUT_SOURCE_VIRTUAL_KBD: from a click on a virtual keyboard
  • INPUT_SOURCE_COMPUTER_KBD: from the computer keyboard
  • INPUT_SOURCE_PLAYED_MUSIC: from the played score