Section Dynamics

Dynamics utility functions

See: Dynamic

Summary

Return type	Function and summary
int	ApplyToAllDynamics(Score score, staves, int firstBar, int lastBar, function filterFunc, function processFunc) Apply a function to all Dynamics in the score, or staff, or in a range of bars.
int	ApplyToAllSelectedDynamics(Score score, function filterFunc, function processFunc, boolean printedStavesOnly) Apply a function to all selected Dynamics, individually selected or inside range selection.
boolean	DynamicIsOttava(Dynamic dynamic) Is `dynamic` an ottava (8va, 8vb, 15ma or 15mb)?
boolean	DynamicIsPedal(Dynamic dynamic) Is `dynamic` an pedal (Ped.
boolean	DynamicIsTempo(Dynamic dynamic) Is `dynamic` a Tempo?
boolean	DynamicIsVelocity(Dynamic dynamic) Is `dynamic` a velocity (power) change?
boolean	EnsureObjectInStaffArea(Score score, Staff staff, obj) Ensure an object is in the Staff area, move it vertically if needed.
Collection	GetDynamicsThatApplyToStaff(Score score, Staff staff) Get all Dynamic that apply to the specified Staff.
number, int, Dynamic	GetTempoAtTime(Score score, int time) Get tempo value and its `Dynamic` object (if applicable) at specified time of the score

Functions

GetTempoAtTime(Score score, int time)

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

Parameter	Type	Default	Description
score	Score		score
time	int		`Symbol.Time`, `Score.TimeBeginSelection`

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

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

DynamicIsTempo(Dynamic dynamic)

Is dynamic a Tempo?

Parameter	Type	Default	Description
dynamic	Dynamic		dynamic

Return: boolean: true if dynamic.Type==DYNAMIC_TEMPO

DynamicIsOttava(Dynamic dynamic)

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

Parameter	Type	Default	Description
dynamic	Dynamic		dynamic

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

DynamicIsPedal(Dynamic dynamic)

Is dynamic an pedal (Ped.

or *)?

Parameter	Type	Default	Description
dynamic	Dynamic		dynamic

Return: boolean: true if dynamic is Ped. or *

DynamicIsVelocity(Dynamic dynamic)

Is dynamic a velocity (power) change?

Parameter	Type	Default	Description
dynamic	Dynamic		dynamic

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

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.

ApplyToAllSelectedDynamics(Score score, function filterFunc, function processFunc, boolean printedStavesOnly)

Apply a function to all selected Dynamics, individually selected or inside range selection.

This browses selected Dynamics on visible (printed) staves from first to last, .

Parameter	Type	Default	Description
score	Score		score
filterFunc	function		Dynamic are tempo, pedal, ottava or... dynamics. The filter function, if not `nil`, is here to apply `processFunc` on the Dynamics you want. This function accepts on Dynamic argument and returns `true` to be processed. You can use DynamicIsTempo, DynamicIsPedal, DynamicIsVelocity or DynamicIsOttava or create your own filter. `nil` means no filter, all kind of Dynamics are processed.
processFunc	function		Function with two Dynamic and Staff arguments, which returns `true` (= 1) if Dynamic has been processed, -1 to stop the process. Other returned values are ignored, process continue to next.
printedStavesOnly	boolean	false	If `true` selected Dynamics on not printed staves are skipped. This has no effect in Scroll mode where all staves are visible.

Return

int: Number of processed Dynamics

Error

if arguments are not valid.

Example



 local nb = ApplyToAllSelectedDynamics(FrontScore(), DynamicIsTempo, function(dyn,staff)
    print(dyn.TempoValue); return true
  end, false)
 print(nb .. " tempo found.")

ApplyToAllDynamics(Score score, staves, int firstBar, int lastBar, function filterFunc, function processFunc)

Apply a function to all Dynamics in the score, or staff, or in a range of bars.

Parameter	Type	Default	Description
score	Score		score
staves		nil	`nil` means all staves a Staff object to apply only to that staff a table of Staff to apply to a list of staves
firstBar	int	1	First bar to start applying the function.
lastBar	int	`score.NumberOfBars`	Last bar to stop applying the function.
filterFunc	function		Dynamic are tempo, pedal, ottava or... dynamics. The filter function, if not `nil`, is here to apply `processFunc` on the Dynamics you want. This function accepts on Dynamic argument and returns `true` to be processed. You can use DynamicIsTempo, DynamicIsPedal, DynamicIsVelocity or DynamicIsOttava or create your own filter. `nil` means no filter, all kind of Dynamics are processed.
processFunc	function		Function with two Dynamic and Staff arguments, which returns `true` (= 1) if Dynamic has been processed, -1 to stop the process. Other returned values are ignored, process continue to next Dynamic.

Return: int: Number of processed Dynamics
Error: if arguments are not valid.
See: ApplyToAllSelectedDynamics