net.charlesames.music.ensemble
Class MidiControl

java.lang.Object
  net.charlesames.utility.common.Disposable
      net.charlesames.utility.entity.Entity
          net.charlesames.utility.entity.WriteableEntity
              net.charlesames.music.ensemble.EnsembleEntity
                  net.charlesames.music.ensemble.MidiControl

All Implemented Interfaces:

EntityContainer

public class MidiControl
extends EnsembleEntity

A MidiControl instance binds a TypeOfMidiControl instance with a ScoreContour that details how control values evolve over time. The parent of a MidiControl is always a EnsembleChoir.

Author:

Charles Ames

Nested Class Summary

Nested classes/interfaces inherited from class net.charlesames.music.ensemble.EnsembleEntity

EnsembleEntity.AttributeTable

Constructor Summary

MidiControl(EnsembleChoir container, TypeOfMidiControl controlType)
Constructor for MidiControl instances.

Method Summary

boolean	check(HtmlBuilder builder) Check this component for errors and inconsistencies
void	checkFactor(double value) Check that the indicated value is suitable as a scale factor.
void	clearUsedChannels() Clear the collection of MIDI channels used by this control.
void	createMidiEvents(Score score, MidiTrack midiTrack, int channel, int key, Ratio startTime, Ratio endTime) Generate MIDI control events over the period from startTime to endTime.
static XmlSpec	createXmlSpec() Create an XML specification for the MidiControl class.
boolean	equals(EnsembleEntity other) Check if this entity has the same class and content as another entity.
static MidiControl	fromXmlNode(org.w3c.dom.Element element, EnsembleChoir choir) Create a new MidiControl instance and fill it with loaded data.
EnsembleChoir	getContainer() Getter for the Container property.
EnsembleContour	getContour() Getter for the Contour property.
TypeOfMidiControl	getControlType() Getter for the ControlType property.
double	getFactor() Getter for the Factor property.
double	getOffset() Getter for the Offset property.
java.lang.String	getPath() Return a description of this entity and its containers.
java.lang.String	getReference() Getter for the Reference property.
void	getXmlData(org.w3c.dom.Element element) Read data from an XML Element.
boolean	hasUsedChannel(EnsembleVoice voice) Test if the MIDI channel associated with the indicated voice has been used by this control.
void	resolve() Dereference the contour specification.
void	setContour(EnsembleContour contour) Setter for the Contour property.
void	setFactor(double factor) Setter for the Factor property.
void	setOffset(double offset) Setter for the Offset property.
void	setReference(java.lang.String reference) Setter for the Reference property.
void	setUsedChannel(EnsembleVoice voice) Flag the MIDI channel associated with the indicated voice as having been used by this control.
void	wipe() Clear all data in this Entity instance.

Methods inherited from class net.charlesames.music.ensemble.EnsembleEntity

buildDescription, copyToClipboard, createIndentCell, createXmlSpec, describeFeature, getEnsemble, logError, predecessor, toString

Methods inherited from class net.charlesames.utility.entity.WriteableEntity

clearXmlSpecs, createXmlSpec, getTagName, getXmlSpec, getXmlSpec, initializeXsd, isPersistent, logError, logError, makeDirty, putXmlData, save, setID, setName, setPersistent, setStatus, toXmlNode

Methods inherited from class net.charlesames.utility.entity.Entity

decrementReferenceCount, dereferenceHandle, dispose, equals, getHandle, getID, getName, getReferenceCount, getStatus, getText, hasContainer, incrementReferenceCount, isModifiable, methodHasOverride, predecessor, resequenceEntities, setContainer, setModifiable, shiftEntitiesDown, shiftEntityDown, shiftEntityUp, successor

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MidiControl

public MidiControl(EnsembleChoir container,
                   TypeOfMidiControl controlType)

Constructor for MidiControl instances.

Parameters:

container - The container.

controlType - The control type. May appear only once in the scope of any voice.

Method Detail

getContainer

public EnsembleChoir getContainer()

Description copied from class: Entity

Getter for the Container property.

Overrides:

getContainer in class EnsembleEntity

Returns:

The assigned Container value.

getReference

public java.lang.String getReference()

Getter for the Reference property. The Reference contains a text path to a EnsembleContour component and thereby to a ScoreContour detailing how the MIDI control changes over time. The resolve() method makes this binding direct.

Returns:

The current reference.

setReference

public void setReference(java.lang.String reference)

Setter for the Reference property. The Reference contains a text path to a EnsembleContour component and thereby to a ScoreContour detailing how the MIDI control changes over time. The resolve() method makes this binding direct.

Parameters:

reference - The intended reference.

clearUsedChannels

public void clearUsedChannels()

Clear the collection of MIDI channels used by this control.

hasUsedChannel

public boolean hasUsedChannel(EnsembleVoice voice)

Test if the MIDI channel associated with the indicated voice has been used by this control.

Parameters:

voice - The indicated voice.

Returns:

True if the MIDI channel associated with the indicated voice has been used by this control; false otherwise.

setUsedChannel

public void setUsedChannel(EnsembleVoice voice)

Flag the MIDI channel associated with the indicated voice as having been used by this control.

Parameters:

voice - The indicated voice.

getOffset

public double getOffset()

Getter for the Offset property. The MIDI control value is calculated by adding the Offset to the Contour value, then multiplying the result by Factor.

Returns:

The current offset.

setOffset

public void setOffset(double offset)

Setter for the Offset property. The MIDI control value is calculated by adding the Offset to the Contour value, then multiplying the result by Factor.

Parameters:

offset - The intended offset.

getFactor

public double getFactor()

Getter for the Factor property. The MIDI control value is calculated by adding the Offset to the Contour value, then multiplying the result by Factor.

Returns:

The current factor. Defaults to unity. Always positive.

checkFactor

public void checkFactor(double value)

Check that the indicated value is suitable as a scale factor.

Parameters:

value - The indicated value.

Throws:

java.lang.IllegalArgumentException - when the value is not positive.

setFactor

public void setFactor(double factor)

Setter for the Factor property. The MIDI control value is calculated by adding the Offset to the Contour value, then multiplying the result by Factor.

Parameters:

factor - The intended factor. Defaults to unity. Must be positive.

getContour

public EnsembleContour getContour()

Getter for the Contour property. The Contour property holds a EnsembleContour instance. The contour indicated by this specification details how the MIDI control changes over time.

Returns:

The current Contour specification

setContour

public void setContour(EnsembleContour contour)

Setter for the Contour property. The Contour property hold a EnsembleContour instance. The contour indicated by this specification details how the MIDI control changes over time.

Parameters:

contour - The current Contour specification

getPath

public java.lang.String getPath()

Description copied from class: Entity

Return a description of this entity and its containers.

Specified by:

getPath in interface EntityContainer

Overrides:

getPath in class Entity

Returns:

A description of this entity and its containers.

getControlType

public TypeOfMidiControl getControlType()

Getter for the ControlType property.

Returns:

The control type.

resolve

public void resolve()

Dereference the contour specification.

check

public boolean check(HtmlBuilder builder)

Check this component for errors and inconsistencies

Overrides:

check in class WriteableEntity

Parameters:

builder - Accumulates an HTML formatted record of each error or inconsistency found.

Returns:

False if any errors or inconsistencies are found; true otherwise.

createMidiEvents

public void createMidiEvents(Score score,
                             MidiTrack midiTrack,
                             int channel,
                             int key,
                             Ratio startTime,
                             Ratio endTime)
                      throws javax.sound.midi.InvalidMidiDataException

Generate MIDI control events over the period from startTime to endTime.

Parameters:

score - The score containing the ScoreContour that drives the control.

midiTrack - The MIDI track within which events will be generated.

channel - The MIDI channel to which the control changes apply.

key - The MIDI key.

startTime - The starting time of the period during which events will be generated.

endTime - The ending time of the period during which events will be generated.

Throws:

javax.sound.midi.InvalidMidiDataException

getXmlData

public void getXmlData(org.w3c.dom.Element element)

Description copied from class: WriteableEntity

Read data from an XML Element.

Overrides:

getXmlData in class WriteableEntity

Parameters:

element - The source Element.

wipe

public void wipe()

Description copied from class: Entity

Clear all data in this Entity instance.

Overrides:

wipe in class Entity

fromXmlNode

public static MidiControl fromXmlNode(org.w3c.dom.Element element,
                                      EnsembleChoir choir)

Create a new MidiControl instance and fill it with loaded data.

Parameters:

element - The XML element that provides the MidiControl data

choir - The Choir which will contain the new MidiControl.

Returns:

The newly created MidiControl instance.

createXmlSpec

public static XmlSpec createXmlSpec()

Create an XML specification for the MidiControl class.

Returns:

The newly created XmlSpec instance.

Throws:

java.lang.RuntimeException - when an XmlSpec instance already exists for the MidiControl class.

equals

public boolean equals(EnsembleEntity other)

Description copied from class: EnsembleEntity

Check if this entity has the same class and content as another entity.

Overrides:

equals in class EnsembleEntity

Parameters:

other - The other entity.

Returns:

True if the two entities have the same class and content; false otherwise.