Measure class

Represents a single bar of music containing an ordered list of MusicalElements.

Use add to append elements. When a TimeSignature is present (or inherited from a previous measure) the add method enforces capacity: adding a note that would exceed the bar's rhythmic value throws a MeasureCapacityException.

Capacity is voice aware. A bar is full when a single voice fills it, not when the sum of every voice does: in polyphonic music each voice runs in parallel and independently spans the whole bar. Elements are grouped by Note.voice / Chord.voice (null means voice defaultVoice) and the rhythmic value of the measure is the maximum of the per-voice sums — see musicalValueByVoice and musicalValueOfVoice.

Example:

final measure = Measure()
  ..add(TimeSignature(numerator: 4, denominator: 4))
  ..add(Note(pitch: const Pitch(step: 'C', octave: 4),
            duration: const Duration(DurationType.whole)));

Two-voice example (both voices legally fill the same 4/4 bar):

final measure = Measure()..add(TimeSignature(numerator: 4, denominator: 4));
for (var i = 0; i < 4; i++) {
  measure.add(Note(pitch: soprano, duration: quarter, voice: 1));
}
for (var i = 0; i < 4; i++) {
  measure.add(Note(pitch: bass, duration: quarter, voice: 2));
}

Subclasses that store elements elsewhere (such as MultiVoiceMeasure, which keeps its content inside Voice objects) override musicalValueByVoice and allElements; iterate a measure through allElements to stay correct for every subclass.

Implementers

MultiVoiceMeasure

Constructors

Measure({bool autoBeaming = true, BeamingMode beamingMode = BeamingMode.automatic, List<List<int>> manualBeamGroups = const [], TimeSignature? inheritedTimeSignature, int? number}): Creates a new Measure.

Properties

allElements → Iterable<MusicalElement>: All the elements of this measure as a single stream.
no setter
autoBeaming ↔ bool: Controls whether notes should be automatically grouped with beams. true = auto-beaming active (default) false = use individual flags
getter/setter pair
beamingMode ↔ BeamingMode: Specific beaming strategy for special cases.
getter/setter pair
currentMusicalValue → double: The current rhythmic value of the measure.
no setter
elements → List<MusicalElement>: All musical elements in this measure, in order.
final
hashCode → int: The hash code for this object.
no setterinherited
inheritedTimeSignature ↔ TimeSignature?: A meter this bar inherits from an earlier one, so that add can enforce capacity on a bar that declares no TimeSignature of its own.
getter/setter pair
isValidlyFilled → bool: Returns true if the measure is correctly filled.
no setter
manualBeamGroups ↔ List<List<int>>: Manual beam groups — list of note index groups to be beamed together. Example: [0, 1, 2, 3, 4] groups notes 0,1,2 into one beam and 3,4 into another.
getter/setter pair
musicalValueByVoice → Map<int, double>: Rhythmic value written in each voice of this measure, keyed by voice number.
no setter
number ↔ int?: Measure number, corresponding to the MEI <measure @n> attribute. null = automatic numbering by the layout engine.
getter/setter pair
remainingValue → double: Returns how much rhythmic time remains in the measure.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited
timeSignature → TimeSignature?: Returns the active time signature for this measure.
no setter

Methods

add(MusicalElement element) → void: Adds a musical element to the measure.
canAddDuration(Duration duration, {int voice = defaultVoice}) → bool: Returns true if there is room to add duration to voice.
musicalValueOfVoice(int voice) → double: Rhythmic value already written in voice (0.0 when the voice is empty).
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
toString() → String: A string representation of this object.
inherited

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

musicalValueOf(MusicalElement element) → double: Calculates the rhythmic value occupied by element.
voiceNumberOf(MusicalElement element) → int: Returns the voice number element belongs to.

Constants

capacityTolerance → const double: Tolerance used when comparing rhythmic values (floating-point safety).
defaultVoice → const int: Voice number attributed to elements that do not declare one.