net.charlesames.music.ensemble
Class EnsembleInstrument

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.ContainerOfInstrumentLinks
                      net.charlesames.music.ensemble.EnsembleInstrument

All Implemented Interfaces:

EntityContainer

public class EnsembleInstrument
extends ContainerOfInstrumentLinks

The {link EnsembleInstrument} class holds attributes that determine the timbre of a note.

Author:

Charles Ames

Nested Class Summary

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

EnsembleEntity.AttributeTable

Method Summary

EnsembleInstrumentVoice	addCapableVoice(EnsembleVoice voice) Add the indicated voice specification to the list of voices capable of playing this instrument.
boolean	check(HtmlBuilder builder) Check this component for errors and inconsistencies
void	checkMidiBank(int value) Check if the indicated value is suitable as a MIDI bank number.
void	checkMidiProgram(int value) Check if the indicated value is suitable as a MIDI program.
void	checkNewUnpitchedSoundText(java.lang.String text) Check if the indicated text parses into a Pitch which can be used to identify an UnpitchedSound.
UnpitchedSound	createUnpitchedSound(Pitch pitch) Create a new UnpitchedSound instance and add it to this EnsembleInstrument.
static XmlSpec	createXmlSpec() Create an XML specification for the EnsembleInstrument class.
boolean	equals(EnsembleEntity other) Check if this entity has the same class and content as another entity.
static EnsembleInstrument	fromXmlNode(org.w3c.dom.Element element, Ensemble ensemble) Create a new EnsembleInstrument instance and fill it with loaded data.
java.util.SortedMap<java.lang.Integer,EnsembleInstrumentVoice>	getCapableVoices()
Ensemble	getContainer() Getter for the Container property.
EnsembleInstrument	getInstrument() Getter for the EnsembleInstrument which either this is or this is contained by.
int	getMidiBank() Getter for the MidiBank property.
int	getMidiElevation() Getter for the MidiElevation property.
int	getMidiPan() Getter for the MidiPan property.
int	getMidiProgram() Getter for the MidiProgram property.
int	getMidiVolume() Getter for the MidiVolume property.
java.lang.String	getMusicXmlDirection() Setter for the MusicXmlDirection property.
Placement	getMusicXmlPlacement() Setter for the MusicXmlPlacement property.
java.lang.String	getPath() Return a description of this entity and its containers.
UnpitchedSound	getUnpitchedSound(Pitch pitch) Get the UnpitchedSound instance associated with the specified pitch.
java.util.SortedMap<java.lang.Integer,UnpitchedSound>	getUnpitchedSounds() Get all UnpitchedSound instances.
java.util.List<EnsembleVoice>	getUnusedVoices() Get the EnsembleVoice instances which are NOT presently among this instrument's capable voices.
boolean	isCapableVoice(EnsembleVoice voice) Test if the indicated voice is capable of playing this instrument.
boolean	isGeneralMidi() Mapping information for MIDI key numbers is defined in UnpitchedSound instances.
void	removeCapableVoice(int voiceID) Remove the indicated voice specification from the list of voices capable of playing this instrument.
void	removeUnpitchedSound(Pitch pitch) Remove the UnpitchedSound instance associated with the specified pitch.
void	setGeneralMidi(boolean generalMidi) Mapping information for MIDI key numbers is defined in UnpitchedSound instances.
boolean	setID(int id) Setter for the ID property.
void	setMidiBank(int midiBank) Setter for the MidiBank property.
void	setMidiElevation(int degrees) Setter for the MidiElevation property.
void	setMidiPan(int degrees) Setter for the MidiPan property.
void	setMidiProgram(int midiProgram) Setter for the MidiProgram property.
void	setMidiVolume(int midiVolume) Setter for the MidiVolume property.
void	setMusicXmlDirection(java.lang.String musicXmlDirection) Getter for the MusicXmlDirection property.
void	setMusicXmlPlacement(Placement musicXmlPlacement) Setter for the MusicXmlPlacement property.
boolean	setName(java.lang.String name) Setter for the Name property.
void	setUnpitched(boolean value) Setter for the Unpitched property.
java.lang.String	toString()
void	wipe() Clear all data in this Entity instance.

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

addInstrumentLink, checkNewInstrumentLinkID, getDefaultInstrumentLinkID, getInstrumentLinks, isUnpitched, removeInstrumentLink, resequenceInstrumentLinks, shiftInstrumentLinkDown, shiftInstrumentLinksDown, shiftInstrumentLinkUp

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 Ensemble getContainer()

Description copied from class: Entity

Getter for the Container property.

Overrides:

getContainer in class EnsembleEntity

Returns:

The assigned Container value.

getInstrument

public EnsembleInstrument getInstrument()

Description copied from class: ContainerOfInstrumentLinks

Getter for the EnsembleInstrument which either this is or this is contained by.

Specified by:

getInstrument in class ContainerOfInstrumentLinks

Returns:

The EnsembleInstrument which either this is or this is contained by.

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.

getCapableVoices

public java.util.SortedMap<java.lang.Integer,EnsembleInstrumentVoice> getCapableVoices()

Returns:

The id-indexed collection of EnsembleVoice instances representing voices which are capable of using this instrument.

getUnusedVoices

public java.util.List<EnsembleVoice> getUnusedVoices()

Get the EnsembleVoice instances which are NOT presently among this instrument's capable voices.

Returns:

An unindexed collection of EnsembleVoice instances.

getMidiProgram

public int getMidiProgram()

Getter for the MidiProgram property. In the MIDI world, the MIDI program (possibly in conjunction with the MIDI bank) determines what sound will be used to play a note. MIDI programs range from 1 to 128, with 0 indicating no program.

Returns:

The current MIDI program.

checkMidiProgram

public void checkMidiProgram(int value)

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

Parameters:

value - The indicated value.

Throws:

java.lang.IllegalArgumentException - when the value falls outside the range from 0 (disabled) 1 to 128.

setMidiProgram

public void setMidiProgram(int midiProgram)

Setter for the MidiProgram property. In the MIDI world, the MIDI program (possibly in conjunction with the MIDI bank) determines what sound will be used to play a note. MIDI programs range from 1 to 128, with 0 indicating no program.

Parameters:

midiProgram - The intended MIDI program.

getMidiVolume

public int getMidiVolume()

Getter for the MidiVolume property. In the MIDI world, the MIDI volume controls the loudness across all channels. MIDI volumes range from 0 to 127.

Returns:

The current MIDI volume.

setMidiVolume

public void setMidiVolume(int midiVolume)

Setter for the MidiVolume property. In the MIDI world, the MIDI volume controls the loudness across all channels. MIDI volumes range from 0 to 127.

Parameters:

midiVolume - The intended MIDI volume.

getMidiPan

public int getMidiPan()

Getter for the MidiPan property. In the MIDI world, the MIDI pan controls the left-right position of the sound. MIDI pan values range from -180 (full left) to 180 (full right). Use this property to set the left-right position of MusicXML instruments. For actual MIDI file generation the pan can be controlled dynamically using a MidiControl.

Returns:

The current MIDI pan.

setMidiPan

public void setMidiPan(int degrees)

Setter for the MidiPan property. In the MIDI world, the MIDI pan controls the left-right position of the sound. MIDI pan values range from -180 (full left) to 180 (full right). Use this property to set the left-right position of MusicXML instruments. For actual MIDI file generation the pan can be controlled dynamically using a MidiControl.

Parameters:

degrees - The intended MIDI pan.

getMidiElevation

public int getMidiElevation()

Getter for the MidiElevation property. In the MIDI world, the MIDI elevation controls the bottom-top position of the sound. MIDI elevation values range from -180 (full bottom) to 180 (full top). Use this property to set the bottom-top position of MusicXML instruments. For actual MIDI file generation the elevation can be controlled dynamically using a MidiControl.

Returns:

The current MIDI elevation.

setMidiElevation

public void setMidiElevation(int degrees)

Setter for the MidiElevation property. In the MIDI world, the MIDI elevation controls the bottom-top position of the sound. MIDI elevation values range from -180 (full bottom) to 180 (full top). Use this property to set the bottom-top position of MusicXML instruments. For actual MIDI file generation the elevation can be controlled dynamically using a MidiControl.

Parameters:

degrees - The intended MIDI elevation.

getMidiBank

public int getMidiBank()

Getter for the MidiBank property. In the MIDI world, the MIDI bank and MIDI program together determine what sound will be used to play a note.

Returns:

The assigned MIDI bank.

checkMidiBank

public void checkMidiBank(int value)

Check if the indicated value is suitable as a MIDI bank number. In the MIDI world, the MIDI bank and MIDI program together determine what sound will be used to play a note.

Parameters:

value - The indicated value.

Throws:

java.lang.IllegalArgumentException - when the value falls outside the range from 0 (disabled) to 128

setMidiBank

public void setMidiBank(int midiBank)

Setter for the MidiBank property. In the MIDI world, the MIDI bank and MIDI program together determine what sound will be used to play a note.

Parameters:

midiBank - The intended MIDI bank.

Throws:

java.lang.IllegalArgumentException - when the value falls outside the range from 0 (disabled) to 128

isGeneralMidi

public boolean isGeneralMidi()

Mapping information for MIDI key numbers is defined in UnpitchedSound instances. The GeneralMidi property of the EnsembleInstrument object indicates whether or not these key numbers conform to the General MIDI standard.

Returns:

True if unpitched MIDI key numbers conform to the General MIDI standard; false otherwise.

setGeneralMidi

public void setGeneralMidi(boolean generalMidi)

Mapping information for MIDI key numbers is defined in UnpitchedSound instances.

Parameters:

generalMidi - True if unpitched MIDI key numbers conform to the General MIDI standard; false otherwise.

getMusicXmlDirection

public java.lang.String getMusicXmlDirection()

Setter for the MusicXmlDirection property. This property is used when a single player (voice) uses several instruments and the player needs to be told when to switch from one to the other. Examples include "arco" versus "pizzicato" or "flute" versus "piccolo".

Returns:

The current MusicXML direction.

setMusicXmlDirection

public void setMusicXmlDirection(java.lang.String musicXmlDirection)

Getter for the MusicXmlDirection property. This property is used when a single player (voice) uses several instruments and the player needs to be told when to switch from one to the other. Examples include "arco" versus "pizzicato" or "flute" versus "piccolo".

Parameters:

musicXmlDirection - The current MusicXML direction.

getMusicXmlPlacement

public Placement getMusicXmlPlacement()

Setter for the MusicXmlPlacement property. This property controls whether MusicXML directions are placed above or below the staff.

Returns:

The current MusicXML placement.

setMusicXmlPlacement

public void setMusicXmlPlacement(Placement musicXmlPlacement)

Setter for the MusicXmlPlacement property. This property controls whether MusicXML directions are placed above or below the staff.

Parameters:

musicXmlPlacement - The intended MusicXML placement.

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.

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.

setUnpitched

public void setUnpitched(boolean value)

Description copied from class: ContainerOfInstrumentLinks

Setter for the Unpitched property.

Parameters:

value - True if the instrument should be unpitched; false otherwise.

isCapableVoice

public boolean isCapableVoice(EnsembleVoice voice)

Test if the indicated voice is capable of playing this instrument.

Parameters:

voice - The indicated voice.

Returns:

True if the indicated voice can play this instrument; false otherwise.

addCapableVoice

public EnsembleInstrumentVoice addCapableVoice(EnsembleVoice voice)

Add the indicated voice specification to the list of voices capable of playing this instrument.

Parameters:

voice - The indicated voice.

Returns:

A new EnsembleInstrumentVoice instance cross referencing the instrument with the voice.

removeCapableVoice

public void removeCapableVoice(int voiceID)

Remove the indicated voice specification from the list of voices capable of playing this instrument.

Parameters:

voiceID - The indicated voice id.

getUnpitchedSounds

public java.util.SortedMap<java.lang.Integer,UnpitchedSound> getUnpitchedSounds()

Get all UnpitchedSound instances.

Returns:

A collection of UnpitchedSound instances, indexed by chroma.

Throws:

java.lang.IllegalArgumentException - when the EnsembleInstrument is not unpitched.

createUnpitchedSound

public UnpitchedSound createUnpitchedSound(Pitch pitch)

Create a new UnpitchedSound instance and add it to this EnsembleInstrument.

Parameters:

pitch - The mapped-from pitch. An IllegalArgumentException is throw if this pitch, or any enharmonic equivalent, is already mapped.

Returns:

The new UnpitchedSound instance.

getUnpitchedSound

public UnpitchedSound getUnpitchedSound(Pitch pitch)

Get the UnpitchedSound instance associated with the specified pitch.

Parameters:

pitch - The specified pitch.

Returns:

The UnpitchedSound instance associated with the specified pitch.

removeUnpitchedSound

public void removeUnpitchedSound(Pitch pitch)

Remove the UnpitchedSound instance associated with the specified pitch.

Parameters:

pitch - The specified pitch.

check

public boolean check(HtmlBuilder builder)

Check this component for errors and inconsistencies

Overrides:

check in class ContainerOfInstrumentLinks

Parameters:

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

Returns:

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

toString

public java.lang.String toString()

Overrides:

toString in class EnsembleEntity

wipe

public void wipe()

Description copied from class: Entity

Clear all data in this Entity instance.

Overrides:

wipe in class ContainerOfInstrumentLinks

fromXmlNode

public static EnsembleInstrument fromXmlNode(org.w3c.dom.Element element,
                                             Ensemble ensemble)

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

Parameters:

element - The XML element that provides the EnsembleInstrument data

ensemble - The Ensemble which will contain the new EnsembleInstrument.

Returns:

The newly created EnsembleInstrument instance.

createXmlSpec

public static XmlSpec createXmlSpec()

Create an XML specification for the EnsembleInstrument class.

Returns:

The newly created XmlSpec instance.

Throws:

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

checkNewUnpitchedSoundText

public void checkNewUnpitchedSoundText(java.lang.String text)

Check if the indicated text parses into a Pitch which can be used to identify an UnpitchedSound.

Parameters:

text - The indicated text.

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 ContainerOfInstrumentLinks

Parameters:

other - The other entity.

Returns:

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