world.sound
Class SoundWorld

java.lang.Object
  world.sound.SoundWorld

All Implemented Interfaces:

SoundConstants

Direct Known Subclasses:

InstrumentTest, KeySoundWorld, Mario, MousePointsSoundWorld, SoundTest

public abstract class SoundWorld
extends java.lang.Object
implements SoundConstants

A Class representing an imperative World with sound/music and the related methods for drawing the world and handling various events. In order to implement a functioning World with sound you must extend this class, and implement an onDraw method. Other handler methods (tickRate, onTick, onMouse, onKey, onRelease, stopWhen, and lastScene) are optional, and can be overridden to add new functionality.

Each of the interaction methods can add Notes (sounds) to be played (e.g., onTick) for a length of time after the event. There are two tune-collections for adding sounds, the first tickTunes, should be added to for notes/sounds that should be played for a specified length of time corresponding to a World event. The second, keyTunes, should be added to for notes/sounds that should be played for as long as the key is pressed; when the key is released the sound will be removed and playing of the note will stop.

See the world.sound.tunes package for more details (Notes, Chords, etc.).

Extending VoidWorld

Below is a simple example of a VoidWorld that adds a new point at each mouse click. The world contains a Scene and a new Circle is placed for each "button-down" event received, and a Note is added to the tickTunes to be played at the current pitch, which is incremented.

   
        import image.*;
        import world.sound.SoundWorld;
        import world.sound.tunes.Note;
        
        public class MousePointsSoundWorld extends SoundWorld{
            // Simple Main Program
            public static void main(String[] args)
            { new MousePointsSoundWorld().bigBang(); }
            
            // The inner Scene
            Scene scene = new EmptyScene(200, 200);
            // The current pitch to be played
            int pitch = noteDownC;
        
            // Create a new World
            MousePointsSoundWorld(){}
            
            // Draw by returning the inner Scene
            public Scene onDraw(){ return this.scene; }
        
            // On a mouse click add a circle to the inner Scene, increment the
            //    current pitch and play a short note
            public void onMouse(int x, int y, String me){
                if(me.equals("button-down")){
                    this.pitch++;
                    this.tickTunes.addNote(WOOD_BLOCK, new Note(this.pitch, 1));
                    this.scene = this.scene.placeImage(
                                     new Circle(20, "solid", "red")
                                           .overlay(new Circle(20, "outline", "black")), x, y);
                }
            }
        }
 

After a few mouse clicks, the window will look something like this, though every mouse click will have a corresponding sound at an increasing pitch:

Field Summary

static double	DEFAULT_TICK_RATE Default Tick rate for the world: ~33 frames per second
static java.lang.String	KEY_ARROW_DOWN Key arrow-down event String
static java.lang.String	KEY_ARROW_LEFT Key arrow-left event String
static java.lang.String	KEY_ARROW_RIGHT Key arrow-right event String
static java.lang.String	KEY_ARROW_UP Key arrow-up event String
TuneCollection	keyTunes The collection of tunes to start playing when a key is pressed, which will automatically removed when the same key is released.
static java.lang.String	MOUSE_DOWN Mouse down (button-down) event String
static java.lang.String	MOUSE_DRAG Mouse down & move (drag) event String
static java.lang.String	MOUSE_ENTER Mouse window enter (enter) event String
static java.lang.String	MOUSE_LEAVE Mouse window leave (leave) event String
static java.lang.String	MOUSE_MOVE Mouse motion (move) event String
static java.lang.String	MOUSE_UP Mouse up (button-up) event String
MusicBox	musicBox A representation of the current state of the MIDI synthesizer.
TuneCollection	tickTunes The collection of tunes to play on tick.

Fields inherited from interface world.sound.tunes.SoundConstants

Accordion, AcousticBass, AcousticBassDrum, AcousticGrandPiano, AcousticGuitar_nylon, AcousticGuitar_steel, AcousticSnare, Agogo, AltoSax, Applause, APPLAUSE, Bagpipe, BAGPIPE, Banjo, BaritoneSax, BASS, BassDrum_1, Bassoon, BIRD_TWEET, BirdTweet, BlownBottle, BrassSection, BreathNoise, BrightAcousticPiano, Cabasa, Celesta, Cello, CELLO, ChineseCymbal, CHOIR, ChoirAahs, ChurchOrgan, Clarinet, Claves, Clavi, ClosedHiHat, Contrabass, Cowbell, CrashCymbal_1, CrashCymbal_2, DistortionGuitar, DrawbarOrgan, Dulcimer, ElectricBass_finger, ElectricBass_pick, ElectricGrandPiano, ElectricGuitar_clean, ElectricGuitar_jazz, ElectricGuitar_muted, ElectricPiano_1, ElectricPiano_2, ElectricSnare, EnglishHorn, Fiddle, Flute, FrenchHorn, FretlessBass, FX_1_rain, FX_2_soundtrack, FX_3_crystal, FX_4_atmosphere, FX_5_brightness, FX_6_goblins, FX_7_echoes, FX_8_scifi, Glockenspiel, GuitarFretNoise, GuitarHarmonics, Gunshot, HandClap, Harmonica, Harpsichord, Helicopter, HiBongo, HighAgogo, HighFloorTom, HighTimbale, HighTom, HiMidTom, HiWoodBlock, HonkyTonkPiano, INSTRUMENT_NAMES, INSTRUMENTS, Kalimba, Koto, Lead_1_square, Lead_2_sawtooth, Lead_3_calliope, Lead_4_chiff, Lead_5_charang, Lead_6_voice, Lead_7_fifths, Lead_8_basslead, LongGuiro, LongWhistle, LowAgogo, LowBongo, LowConga, LowFloorTom, LowMidTom, LowTimbale, LowTom, LowWoodBlock, Maracas, Marimba, MelodicTom, MusicBox, MuteCuica, MutedTrumpet, MuteHiConga, MuteTriangle, NoteA, NoteAp, NoteB, NoteC, NoteCp, NoteD, NoteDownA, NoteDownAp, NoteDownB, NoteDownC, NoteDownCp, NoteDownD, NoteDownDp, NoteDownE, NoteDownF, NoteDownFp, NoteDownG, NoteDownGp, NoteDp, NoteE, NoteF, NoteFp, NoteG, NoteGp, NoteUpA, NoteUpAp, NoteUpB, NoteUpC, NoteUpCp, NoteUpD, NoteUpDp, NoteUpE, NoteUpF, NoteUpFp, NoteUpG, NoteUpGp, Oboe, Ocarina, OpenCuica, OpenHiConga, OpenHiHat, OpenTriangle, OrchestraHit, OrchestralHarp, ORGAN, OverdrivenGuitar, Pad_1_newage, Pad_2_warm, Pad_3_polysynth, Pad_4_choir, Pad_5_bowed, Pad_6_metallic, Pad_7_halo, Pad_8_sweep, PanFlute, PedalHiHat, PERCUSSION, PercussiveOrgan, PIANO, Piccolo, PizzicatoStrings, Recorder, ReedOrgan, ReverseCymbal, RideBell, RideCymbal_2, RideCymbal1, RockOrgan, SAX, Seashore, SEASHORE, Shamisen, Shanai, ShortGuiro, ShortWhistle, SideStick, Sitar, Skakuhachi, SlapBass_1, SlapBass_2, SopranoSax, SplashCymbal, STEELDRUM, SteelDrums, StringEnsemble_1, StringEnsemble_2, SynthBass_1, SynthBass_2, SynthBrass_1, SynthBrass_2, SynthDrum, SynthStrings_1, SynthStrings_2, SynthVoice, TaikoDrum, Tambourine, TangoAccordion, TELEPHONE, TelephoneRing, TenorSax, Timpani, TinkleBell, TremoloStrings, Trombone, Trumpet, Tuba, TUBA, TubularBells, Vibraphone, Vibraslap, Viola, Violin, VIOLIN, VoiceOohs, Whistle, WOOD_BLOCK, Woodblock, Xylophone

Constructor Summary

SoundWorld()
Default constructor.

Method Summary

SoundWorld	bigBang() Kick off the interaction/animation.
boolean	equals(java.lang.Object o) Overridden equality to method.
Scene	lastScene() Returns the Scene that should be displayed when the interaction/animation completes (stopWhen() returns true).
abstract Scene	onDraw() Return a visualization of this World as a Scene.
void	onKey(java.lang.String event) Change this World when a key event is triggered.
void	onMouse(int x, int y, java.lang.String event) Change this World when a mouse event is triggered.
void	onRelease(java.lang.String event) Change this World when a key is released.
void	onTick() Change this World based on the Tick of the clock.
boolean	stopWhen() Determine if the World/interaction/animation should be stopped.
double	tickRate() Return the tick rate for this World in seconds.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_TICK_RATE

public static double DEFAULT_TICK_RATE

Default Tick rate for the world: ~33 frames per second

MOUSE_DOWN

public static java.lang.String MOUSE_DOWN

Mouse down (button-down) event String

MOUSE_UP

public static java.lang.String MOUSE_UP

Mouse up (button-up) event String

MOUSE_ENTER

public static java.lang.String MOUSE_ENTER

Mouse window enter (enter) event String

MOUSE_LEAVE

public static java.lang.String MOUSE_LEAVE

Mouse window leave (leave) event String

MOUSE_MOVE

public static java.lang.String MOUSE_MOVE

Mouse motion (move) event String

MOUSE_DRAG

public static java.lang.String MOUSE_DRAG

Mouse down & move (drag) event String

KEY_ARROW_UP

public static java.lang.String KEY_ARROW_UP

Key arrow-up event String

KEY_ARROW_DOWN

public static java.lang.String KEY_ARROW_DOWN

Key arrow-down event String

KEY_ARROW_LEFT

public static java.lang.String KEY_ARROW_LEFT

Key arrow-left event String

KEY_ARROW_RIGHT

public static java.lang.String KEY_ARROW_RIGHT

Key arrow-right event String

musicBox

public MusicBox musicBox

A representation of the current state of the MIDI synthesizer.

tickTunes

public TuneCollection tickTunes

The collection of tunes to play on tick. Any tunes added after an event will begin playing as soon as the event is completely processed and will finish playing when the sound/Note's duration has elapsed.

keyTunes

public TuneCollection keyTunes

The collection of tunes to start playing when a key is pressed, which will automatically removed when the same key is released.

Constructor Detail

SoundWorld

public SoundWorld()

Default constructor. Simply initializes the tune/music classes.

Method Detail

onDraw

public abstract Scene onDraw()

Return a visualization of this World as a Scene. See EmptyScene, Scene.placeImage(Image, int, int), and Scene.addLine(int, int, int, int, String) for documentation on constructing Scenes

tickRate

public double tickRate()

Return the tick rate for this World in seconds. For example, 0.5 means two ticks per second. The rate is only accessed when bigBang() is initially called and the window is created.

onTick

public void onTick()

Change this World based on the Tick of the clock. This method is called to get the update the World on each clock tick. Sounds (Notes) to play starting on the current tick may be added to the tickTunes tune-collection to be played for a specified length of time. Notes will stop playing automatically when the amount of time corresponding to the note's duration has elapsed.

onMouse

public void onMouse(int x,
                    int y,
                    java.lang.String event)

Change this World when a mouse event is triggered. x and y are the location of the event in the window, and event is a String that describes what kind of event occurred.

Possible Mouse Events

"button-down" :	The user presses a mouse button in the World window
"button-up" :	The user releases a mouse button in the World window
"move" :	The user moves the mouse in the World window
"drag" :	The user holds a mouse button and moves the mouse in the World window
"enter" :	The user moves the mouse in-to the World window
"leave" :	The user moves the mouse out-of the World window

Sounds (Notes) to play starting when a certain mouse event occurs may be added to the tickTunes tune-collection to be played for a specified length of time. Notes will stop playing automatically when the amount of time corresponding to the note's duration has elapsed.

onKey

public void onKey(java.lang.String event)

Change this World when a key event is triggered. The given event is a String that describes which key was pressed.

Special Key

"up" :	The user presses the up-arrow key
"down" :	The user presses the down-arrow key
"left" :	The user presses the left-arrow key
"right" :	The user presses the right-arrow key

Other keys generate a single character String that represents the key pressed. For example, Pressing the B key on the keyboard generates "b" as an event. If the shift key is held while pressing B then "B" is generated.

Sounds (Notes) to play when the given key is pressed may be added to the keyTunes tune-collection to be played until the same key is released. Notes will not stop playing until the key is released.

Sounds to be played for a specific length of time after a certain key press (i.e., not until the key is released) may be added to the tickTunes tune-collection (instead of keyTunes) played until amount of time corresponding to the note's duration has elapsed.

onRelease

public void onRelease(java.lang.String event)

Change this World when a key is released. The given event is a String that describes which key was released.

Special Keys

"up" :	The user presses the up-arrow key
"down" :	The user presses the down-arrow key
"left" :	The user presses the left-arrow key
"right" :	The user presses the right-arrow key

Other keys generate a single character String that represents the key released. For example, Pressing then releasing the B key on the keyboard generates "b" as an onKey event and again as an onRelease event. If the shift key is held while pressing/releasing B then "B" is generated.

Sounds (Notes) that were added to the keyTunes tune-collection on a previous key press will be stopped.

stopWhen

public boolean stopWhen()

Determine if the World/interaction/animation should be stopped. Returning a value of true discontinues all events (mouse, key, ticks) and causes lastScene() to be used to draw the final Scene.

lastScene

public Scene lastScene()

Returns the Scene that should be displayed when the interaction/animation completes (stopWhen() returns true).

bigBang

public SoundWorld bigBang()

Kick off the interaction/animation. This method returns the final state of the world after the user closes the World window.

equals

public boolean equals(java.lang.Object o)

Overridden equality to method. Returns false to make sure that changes to the world are redrawn every time.

Overrides:

equals in class java.lang.Object