net.charlesames.music.ensemble
Class EnsembleVoice

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.EnsembleVoice

All Implemented Interfaces:

EntityContainer

public class EnsembleVoice
extends EnsembleEntity

The EnsembleVoice class hold properties. The parent of a EnsembleVoice is always a EnsembleChoir.

Author:

Charles Ames

Nested Class Summary

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

EnsembleEntity.AttributeTable

Method Summary

boolean	check(HtmlBuilder builder) Check this component for errors and inconsistencies
void	checkMidiChannel(int value) Check if the indicated value is suitable as a MIDI channel.
void	checkMusicXmlVoiceNumber(int value) Check if the indicated value is suitable as a MusicXML voice number.
static XmlSpec	createXmlSpec() Create an XML specification for the EnsembleVoice class.
boolean	equals(EnsembleEntity other) Check if this entity has the same class and content as another entity.
static EnsembleVoice	fromXmlNode(org.w3c.dom.Element element, EnsembleChoir choir) Create a new EnsembleVoice instance under a Choir and fill it with loaded data.
java.util.List<EnsembleInstrument>	getCapableInstruments() Get the instruments which this voice is capable of playing.
EnsembleChoir	getContainer() Getter for the Container property.
EnsembleContour	getContourByID(int id) Search by id all defined EnsembleContour instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.
EnsembleContour	getContourByName(java.lang.String name) Search by name all defined EnsembleContour instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.
java.util.SortedMap<java.lang.Integer,EnsembleContour>	getContoursByID() List all defined EnsembleContour instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.
EnsembleInstrument	getDefaultInstrument() Getter for the DefaultInstrument property.
java.lang.String	getDefaultMidiInstrumentName() Get the name of the default instrument.
int	getMidiChannel() Getter for the MidiChannel property.
java.lang.String	getMidiChannelKey() Get a colon-delimited string combining the MIDI track name, device name, and channel number.
java.util.SortedMap<java.lang.String,MidiControl>	getMidiControls() List all defined MidiControl instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.
java.lang.String	getMidiDeviceName() Setter for the MidiDeviceName property.
java.lang.String	getMidiTrackName() Setter for the MidiTrackName property.
Placement	getMusicXmlPlacement() Getter for the MusicXmlPlacement property.
MusicXmlStaff	getMusicXmlStaff() Getter for the MusicXmlStaff property.
int	getMusicXmlVoiceNumber() Getter for the MusicXmlVoiceNumber property.
java.lang.String	getPath() Return a description of this entity and its containers.
void	resolve() Resolve object references
void	setChoir(EnsembleChoir choir) Move a EnsembleVoice from its current parent EnsembleChoir to a different EnsembleChoir.
void	setDefaultInstrument(EnsembleInstrument defaultInstrument) Setter for the DefaultInstrument property.
boolean	setID(int id) Setter for the ID property.
void	setMidiChannel(int midiChannel) Setter for the MidiChannel property.
void	setMidiDeviceName(java.lang.String midiDeviceName) Setter for the MidiDeviceName property.
void	setMidiTrackName(java.lang.String midiTrackName) Getter for the MidiTrackName property.
void	setMusicXmlPlacement(Placement placement) Setter for the MusicXmlPlacement property.
void	setMusicXmlStaff(MusicXmlStaff staff) Setter for the MusicXmlStaff property.
void	setMusicXmlVoiceNumber(int musicXmlVoiceNumber) Setter for the MusicXmlVoiceNumber property.
boolean	setName(java.lang.String name) Setter for the Name property.
java.lang.String	toString()
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

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

clearXmlSpecs, createXmlSpec, getTagName, getXmlData, getXmlSpec, getXmlSpec, initializeXsd, isPersistent, logError, logError, makeDirty, putXmlData, save, 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

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.

getDefaultInstrument

public EnsembleInstrument getDefaultInstrument()

Getter for the DefaultInstrument property. This method is used by the Ashton score-generating engine to supply an instrument when one has not been specifically indicated.

Returns:

The current default EnsembleInstrument.

getCapableInstruments

public java.util.List<EnsembleInstrument> getCapableInstruments()

Get the instruments which this voice is capable of playing.

Returns:

An unindexed collection of EnsembleInstrument instances.

setDefaultInstrument

public void setDefaultInstrument(EnsembleInstrument defaultInstrument)

Setter for the DefaultInstrument property.

Parameters:

defaultInstrument - The intended default EnsembleInstrument. The current voice must already be capable of using this instrument.

setChoir

public void setChoir(EnsembleChoir choir)

Move a EnsembleVoice from its current parent EnsembleChoir to a different EnsembleChoir.

Parameters:

choir - The destination {link Choir} instance.

setName

public boolean setName(java.lang.String name)

Description copied from class: Entity

Setter for the Name property.

Overrides:

setName in class WriteableEntity

Parameters:

name - The intended Name value.

Returns:

True if a Name change actually happened; false otherwise.

setID

public boolean setID(int id)

Description copied from class: Entity

Setter for the ID property.

Overrides:

setID in class WriteableEntity

Parameters:

id - The intended ID value.

Returns:

True if an ID change actually happened; false otherwise.

getMidiChannelKey

public java.lang.String getMidiChannelKey()

Get a colon-delimited string combining the MIDI track name, device name, and channel number.

Returns:

A colon-delimited string combining the MIDI track name, device name, and channel number.

getMidiChannel

public int getMidiChannel()

Getter for the MidiChannel property. If an Ensemble is MIDI-capable but not MusicXML capable, then each voice in the ensemble must have a unique MidiChannel value. If the Ensemble is both MIDI-capable and MusicXML capable, Then the combination of MidiChannel and MusicXmlVoiceNumber must be unique in each voice

Returns:

The current MIDI channel.

checkMidiChannel

public void checkMidiChannel(int value)

Check if the indicated value is suitable as a MIDI channel.

Parameters:

value - The indicated value.

Throws:

java.lang.IllegalArgumentException - when the value falls outside the range from 1 to 16.

setMidiChannel

public void setMidiChannel(int midiChannel)

Setter for the MidiChannel property. If an Ensemble is MIDI-capable but not MusicXML capable, then each voice in the ensemble must have a unique MidiChannel value. If the Ensemble is both MIDI-capable and MusicXML capable, Then the combination of MidiChannel and MusicXmlVoiceNumber must be unique in each voice

Parameters:

midiChannel - The intended MIDI channel. Ranges from 1 to 16.

Throws:

java.lang.IllegalArgumentException - when the value falls outside the range from 1 to 16.

getMidiTrackName

public java.lang.String getMidiTrackName()

Setter for the MidiTrackName property. This property should be always blank for single-track MIDI files (type 0) and never blank for multi-track MIDI files (type 1). If two voices share the same MidiTrackName, the will be merged into the same track.

Returns:

The current MIDI track name.

setMidiTrackName

public void setMidiTrackName(java.lang.String midiTrackName)

Getter for the MidiTrackName property. This property should be always blank for single-track MIDI files (type 0) and never blank for multi-track MIDI files (type 1). If two voices share the same MidiTrackName, the will be merged into the same track.

Parameters:

midiTrackName - The intended MIDI track name.

getMidiDeviceName

public java.lang.String getMidiDeviceName()

Setter for the MidiDeviceName property. Single MIDI synthesizers are limited to a maximum of 16 MIDI channels. If you want more channels you need an advanced controller that can route MIDI commands to different synthesizers, each being identified by a separate MIDI device name. Use this property only if you have the equipment to support it.

Returns:

The current MIDI device name.

setMidiDeviceName

public void setMidiDeviceName(java.lang.String midiDeviceName)

Setter for the MidiDeviceName property. Single MIDI synthesizers are limited to a maximum of 16 MIDI channels. If you want more channels you need an advanced controller that can route MIDI commands to different synthesizers, each being identified by a separate MIDI device name. Use this property only if you have the equipment to support it.

Parameters:

midiDeviceName - The current MIDI device name.

getMusicXmlStaff

public MusicXmlStaff getMusicXmlStaff()

Getter for the MusicXmlStaff property. In MusicXML, a "part" can comprise one or more staves (consider a grand staff), and each staff can accommodate one or two voices. To map from an Ensemble to MusicXML, you must therefore fill in three EnsembleVoice properties: MusicXmlStaff, MusicXmlVoiceNumber, and MusicXmlPlacement. Each voice in a MusicXML-capable Ensemble must have a unique combination of part, staff id, and voice id.

Returns:

The current MusicXML staff.

setMusicXmlStaff

public void setMusicXmlStaff(MusicXmlStaff staff)

Setter for the MusicXmlStaff property. In MusicXML, a "part" can comprise one or more staves (consider a grand staff), and each staff can accommodate one or two voices. To map from an Ensemble to MusicXML, you must therefore fill in three EnsembleVoice properties: MusicXmlStaff, MusicXmlVoiceNumber, and MusicXmlPlacement. Each voice in a MusicXML-capable Ensemble must have a unique combination of part, staff id, and voice id.

Parameters:

staff - The intended MusicXML staff.

getMusicXmlVoiceNumber

public int getMusicXmlVoiceNumber()

Getter for the MusicXmlVoiceNumber property. In MusicXML, a "part" can comprise one or more staves (consider a grand staff), and each staff can accommodate one or two voices. To map from an Ensemble to MusicXML, you must therefore fill in five EnsembleVoice properties: MusicXmlPart, MusicXmlStaffID, DefaultClef, MusicXmlVoiceNumber, and MusicXmlPlacement. Each voice in a MusicXML-capable Ensemble must have a unique combination of part, staff id, and voice number.

Returns:

The current MusicXML voice number.

setMusicXmlVoiceNumber

public void setMusicXmlVoiceNumber(int musicXmlVoiceNumber)

Setter for the MusicXmlVoiceNumber property. In MusicXML, a "part" can comprise one or more staves (consider a grand staff), and each staff can accommodate one or two voices. To map from an Ensemble to MusicXML, you must therefore fill in five EnsembleVoice properties: MusicXmlPart, MusicXmlStaffID, DefaultClef, MusicXmlVoiceNumber, and MusicXmlPlacement. Each voice in a MusicXML-capable Ensemble must have a unique combination of part, staff id, and voice id. Call this method after you have set the MusicXmlPart, since the range of allowable voice id's is determined by the part.

Parameters:

musicXmlVoiceNumber - The intended MusicXML voice id.

checkMusicXmlVoiceNumber

public void checkMusicXmlVoiceNumber(int value)

Check if the indicated value is suitable as a MusicXML voice number.

Parameters:

value -

getMusicXmlPlacement

public Placement getMusicXmlPlacement()

Getter for the MusicXmlPlacement property. In MusicXML, a "part" can comprise one or more staves (consider a grand staff), and each staff can accommodate one or two voices. To map from an Ensemble to MusicXML, you must therefore fill in five EnsembleVoice properties: MusicXmlPart, MusicXmlStaffID, DefaultClef, MusicXmlVoiceNumber, and MusicXmlPlacement. Each voice in a MusicXML-capable Ensemble must have a unique combination of part, staff id, and voice id.

Returns:

The current MusicXML placement (above or below).

setMusicXmlPlacement

public void setMusicXmlPlacement(Placement placement)

Setter for the MusicXmlPlacement property. In MusicXML, a "part" can comprise one or more staves (consider a grand staff), and each staff can accommodate one or two voices. To map from an Ensemble to MusicXML, you must therefore fill in five EnsembleVoice properties: MusicXmlPart, MusicXmlStaffID, DefaultClef, MusicXmlVoiceNumber, and MusicXmlPlacement. Each voice in a MusicXML-capable Ensemble must have a unique combination of part, staff id, and voice id.

When two Ensemble voices occupy the same MusicXML staff, the

Parameters:

placement - The current MusicXML placement (above or below).

getMidiControls

public java.util.SortedMap<java.lang.String,MidiControl> getMidiControls()

List all defined MidiControl instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.

Returns:

A collection of MidiControl instances, indexed by control name.

getContoursByID

public java.util.SortedMap<java.lang.Integer,EnsembleContour> getContoursByID()

List all defined EnsembleContour instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.

Returns:

A collection of EnsembleContour instances, indexed by contour id.

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.

getContourByName

public EnsembleContour getContourByName(java.lang.String name)

Search by name all defined EnsembleContour instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.

Parameters:

name - The indicated name.

Returns:

A EnsembleContour instance with the indicated name (null if not found).

getContourByID

public EnsembleContour getContourByID(int id)

Search by id all defined EnsembleContour instances, working down the hierarchy from the Ensemble itself through each EnsembleChoir and sub-choir that contains this EnsembleVoice.

Parameters:

id - The indicated id.

Returns:

A EnsembleContour instance with the indicated id (null if not found).

getDefaultMidiInstrumentName

public java.lang.String getDefaultMidiInstrumentName()

Get the name of the default instrument.

Returns:

The name of the default instrument (null if undefined).

resolve

public void resolve()

Resolve object references

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.

wipe

public void wipe()

Description copied from class: Entity

Clear all data in this Entity instance.

Overrides:

wipe in class Entity

fromXmlNode

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

Create a new EnsembleVoice instance under a Choir and fill it with loaded data.

Parameters:

element - The XML element that provides the EnsembleVoice data

choir - The Choir which will contain the new EnsembleVoice.

Returns:

The newly created EnsembleVoice instance.

createXmlSpec

public static XmlSpec createXmlSpec()

Create an XML specification for the EnsembleVoice class.

Returns:

The newly created XmlSpec instance.

Throws:

java.lang.RuntimeException - when an XmlSpec instance already exists for the EnsembleVoice 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.

toString

public java.lang.String toString()

Overrides:

toString in class EnsembleEntity