Section Staves

Staff utility functions

See: Staff; StavesGroups; StavesGroup

Summary

Return type	Function and summary
table	ChooseStaves(Score score, boolean multiple, boolean visibleOnly, function filterFunc, function selectFunc, int minNbOfChoice, int maxNbOfChoice) Ask the user to choose one or multiple staves.
	CopyBarNumberings(Staff source, Staff dest) Copy bar numberings settings from one staff to another.
int	DeleteDisabledCurves(Staff staff) Remove the parameter curves that have been disabled.
int	DeleteEmptyCurves(Staff staff) Remove the empty parameter curves when they have no values.
boolean	EnsureObjectInStaffArea(Score score, Staff staff, obj) Ensure an object is in the Staff area, move it vertically if needed.
table	GetChordsFromStaff(Score score, Staff staff, boolean held) Get the chords of a Staff from the chord line and return detailed informations.
Collection	GetDynamicsThatApplyToStaff(Score score, Staff staff) Get all Dynamic that apply to the specified Staff.
table	GetStavesGroups(Score score, Staff staff) Get all StavesGroups of the `score` or containing `staff` if this argument is provided.
table	GetStavesInGroup(StavesGroup sg) Return an array of staves in StavesGroup `sg`
	JumpAndSelectBar(Score score, int barN, Staff staffBegin, Staff stafEnd) Jump to the requested bar number and select it, all staves or the requested staff if not `nil`.
int	SMApplyToAllSelectedSymbols(Score score, function processFunc) Apply a function to all selected symbols, individually selected or continous selection.
int	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.
	SetGhostRestDisplayMode(Score score, int grdm) Set the ghost rest display mode for all staves in all views.
	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.

Functions

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.

Parameter	Type	Default	Description
score	Score		score
processFunc	function		Function with a singl Symbol argument, and returns `true` if symbol has been processed.

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.

Parameter	Type	Default	Description
score	Score		score
staff	Staff	nil	`nil` menas all staves.
firstBar	int	1	First bar to start applying the function.
lastBar	int	`score.NumberOfBars`	Last bar to stop applying the function.
processFunc	function		Function with a singl Symbol argument, and returns `true` if symbol has been processed.

Return: int: Number of processed symbols
Error: if arguments have wrong types.
See: SMApplyToAllSelectedSymbols

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

Parameter	Type	Default	Description
score	Score		score
staff	Staff		staff

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

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.

Parameter	Type	Default	Description
score	Score		score
staff	Staff		staff
held	boolean	nil	Hold chord until next is encountered? If `nil`, use the chord line setup of the staff. HA needs underscore (`_`) to hold a chord, but this is unsightly for printing, and works randomly.

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

EnsureObjectInStaffArea(Score score, Staff staff, obj)

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

Parameter	Type	Description
score	Score	score
staff	Staff	staff
obj		Object: Dynamic, StaffText, FXProcessor, Picture

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

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:

`ChooseStaves(...)` displays a menu with checkboxes.

Parameter	Type	Default	Description
score	Score		score
multiple	boolean	true	`true` if several staves can be chosen, `false` if only one staff can be chosen.
visibleOnly	boolean	true	`true` if only visible staves are provided.
filterFunc	function		Function that receives Score and Staff arguments, returns `true` if the staff appears in list, `false` if not.
selectFunc	function		Function that receives Score and Staff arguments, returns `true` if the staff is selected by default, `false` if not selected.
minNbOfChoice	int	1	Minimum number of staves to choose, `0` means user can choose no staff. No effect if `multiple` is false.
maxNbOfChoice	int	0	Maximum number of staves to choose, `0` means no limit. No effect if `multiple` is false.

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.

Parameter	Type	Default	Description
score	Score		score
staff	Staff	nil	If `nil`, return all StavesGroups of the `score`, else return the ones containing `staff`.

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

Parameter	Type	Default	Description
sg	StavesGroup		sg

Return: table: Array of Staff

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.

Parameter	Type	Description
score	Score	score
staff	Staff	staff
state	boolean	`true` to show ambitus, `false` to hide it.

JumpAndSelectBar(Score score, int barN, Staff staffBegin, Staff stafEnd)

Jump to the requested bar number and select it, all staves or the requested staff if not nil.

Try to position the selected bar near the center of the screen, unlike Score.JumpToBar(...) which also doesn't select.

Parameter	Type	Default	Description
score	Score		score
barN	int		Bar number, must be lower or equal to Score.NumberOfBars
staffBegin	Staff	nil	If not `nil`, first or only staff to select, instead of all staves.
stafEnd	Staff	nil	If not `nil`, last staff to select

Error: if barN > score.NumberOfBars or staff is not nil and not a Staff.

DeleteDisabledCurves(Staff staff)

Remove the parameter curves that have been disabled.

Parameter	Type	Default	Description
staff	Staff		staff

Return: int: Number of deleted curves

DeleteEmptyCurves(Staff staff)

Remove the empty parameter curves when they have no values.

Parameter	Type	Default	Description
staff	Staff		staff

Return: int: Number of deleted curves

CopyBarNumberings(Staff source, Staff dest)

Copy bar numberings settings from one staff to another.

Parameter	Type	Default	Description
source	Staff		source
dest	Staff		dest

SetGhostRestDisplayMode(Score score, int grdm)

Set the ghost rest display mode for all staves in all views.

Parameter	Type	Default	Description
score	Score		score
grdm	int		0 = don't display 1 = display with a mark 2 = display whole rest in empty bars 3 = display with real rests