Class: EventList

Environment: Siren
Superclass: Siren.MusicEvent
Category: Music-Events
Instance variables: events

Instances of class EventList (subclass of DurationEvent), are used for holding onto multiple timed events. EventLists are events themselves and can have arbitrary properties as well as a collection of (relative start time -> event) associations.

Class EventList implements much collection-style protocol for event processing, as well as having special block application methods. All EventList algorithms are recurrsive in order to handle arbitrarily-deep hierarchical EventLists (possible because EventList is a subclass of DurationEvent). The class also has numerous powerful and flexible instance creation methods.

Instance Variables:
events MEvent)>
the list's events, time/event associations sorted by relative start times
index the current position (used in scheduling)
startedAt the clock value when I sterted

Standard properties are #tempoScale for the tempo scaling factor (used by the CMN editors as the MS/whole note scale), and #code (#duration, #delta, or #startStop) to support different event coding schemes. The class also supports typed links to other event lists, e.g., "eList1 isTonicAnswerOf: eList2" or "eList1 hasPreviousVersion: eList2", which can be very useful properties in editors and browsers.

The global dictionary EventLists holds onto instances that can be referenced with their name symbols; these can have gensym-like names such as #temp.23. Creating a named EventList automatically adds it to the global dictionary. There are tools for browsing and maintaining this dictionary.

accessing

addModifier: aModifier
Add the given event modifier to the receiver's special modifier collection

code
Answer a symbol about the receiver's events' coding, usually #durations or #noteOnOff

code: aSymbol
Set the code about the receiver's events, usually #durations or #noteOnOff

deepCopy
Answer a careful deep copy.

defaultEventClass
Answer the default note event class.

name
Answer the receiver's name.

name: aName
Set the receiver's name.

next
Answer the next event in the list.

removeModifier: aModifier
Remove the given event modifier from the receiver's collection.

shallowCopy
Answer a shallow copy of the receiver's events.

size
Answer the number of events in the receiver.

tempo: someValue
Set the tempo to scale the events by.

voices
Answer the collection of voices used by thereceiver event list.

code conversion

continueProperties
Fill in missing properties with values that are continued from previous ones.

findNoteOff: anAssociation
Locate the noteOff event that corresponds to anAssociation; answer the sum of the delta times between (the duration)

setDurations
Take a delta-time encoded event list and determine the durations.

collecting

collect: aBlock
Iterate over the receiver's events with the given block

collectAll: aBlock
Iterate over the receiver's events with the given block

do: aBlock
Iterate over the receiver's event associations with the given block

eventsDo: aBlock
Iterate over the receiver's events with the given block

excerptFrom: start to: end
Answer a hierarchical list delineated by the given times.

expanded
Expand all sub-event lists and answer one large flat list.

expandedFrom: start to: end
Expand all sub-event lists and answer one flat list with events between the given times.

group: selection
Group the argument's events as a sub-event list in the receiver's list.

includes: anAss
Answer whether the given association is in the receiver's event list.

keysAndValuesDo: aBlock

remove: anA
Remove the given event from the receiver's collection

select: aBlock
Iterate over the receiver's events with the given block

selectAll: aBlock
Iterate over the receiver's events with the given block

selectKey: aBlock
Iterate over the receiver's events with the given block

selectValue: aBlock
Iterate over the receiver's events with the given block

timesDo: aBlock
Iterate over the receiver's events' relative start times with the given block

printing

asExplorerString

asExplorerString: ignored

printOn: aStream
Print out the receiver's events on the argument.

readDataFrom: aDataStream size: size
Read a new event list from the given stream using the compact format.

storeDataOn: aDataStream
Store myself on a DataStream. Answer self.

storeOn: aStream
Store source code for the receiver's events on the argument.

storeOnFile: aName
Store out the receiver's events on the file named by the argument.

templateFields
Answer the field names for the instances of the receiver class.

processing

addValue: theValue toProp: theSelector
Add theValue to the aspect refered to by theSelector of all events.

applyBlock: theBlock toProp: theSelector
Apply the given block to the aspect refered to by theSelector of all events.

applyFunction: aFunction to: aSelector
Apply the given function to the range of the given selector

applyFunction: aFunction to: aSelector startingAt: sTime
Apply the given function to the range of the given selector starting at sTime.

chooseRange: theRange toProp: theSelector
Select a value from the given range for the aspect refered to by theSelector of all events.

edit
Open your favorite graphical editor on the receiver (left-shift-sensitive)

scale: theSelector by: theValue
Multiply the aspect refered to by theSelector of all events by theValue.

scaleStartTimesBy: theValue
Multiply the start times all events by theValue.

scaleValue: theValue toProp: theSelector
Multiply the aspect refered to by theSelector of all events by theValue.

setValue: theValue toProp: theSelector
Set the aspect refered to by theSelector of all events to theValue.

spreadValue: theRandomPercent toProp: theSelector
Spread the given property of all events by the given random range (%+-).

testing

hasItems
Answer whether or not the receiver has items or components (true).

isEmpty
Answer whether the receiver is an event list (true).

isEventList
Answer whether the receiver is an event list (true).

species
Answer EventList.

scheduling

loop
Play the event list by passing it off to the event scheduler.

nextTime: now
Answer the time of the next appointment

nextTimeFor: ass
Answer the time delay between the given event association and the one that follows it.

play
Play the event list by passing it off to the event scheduler.

playOn: aVoice
Play the event list on the voice by expanding its events

playOn: aVoice at: startTime
Play the event list on the voice by expanding its events

scheduleAt: aTime
Expand an eventList for the appointment scheduler.

stop
Play the event list by passing it off to the event scheduler.

initialize-release

empty
Throw away the receiver's events.

initializeAnonymous
Initialize an un-named instance with default state.

initializeNamed: aName
Initialize a named instance with default state.

release
Flush the receiver.

event accessing

, anEorA
Add a new event or association to the receiver.

add: anEorA
Add a new event or association to the receiver.

add: anEvent at: aTime
Add a new event to the receiver at the given relative start time.

addAll: anEventList
Add the given event list's events to the receiver.

eventKeys
Answer the keys (durations) of the receiver's eventDictionary.

eventNear: aPoint
Answer an event within a reasonable distance (100 msec.) of the given point's x.

eventNearestTime: aTime
Answer an event within a reasonable distance (32 msec.) of the given point.

eventNearTime: aTime
Answer an event within a reasonable distance (32 msec.) of the given point.

events
Answer the receiver's eventDictionary.

events: anEL
Set the receiver's eventDictionary.

eventValues
Answer the values (events) of the receiver's eventDictionary.

recomputeDuration
Recompute the total duration of the receiver.

private

map: anAssociation
Map the receiver's special properties and/or eventModifiers onto the given event.

map: anAssociation at: startTime
Map the receiver's special properties and/or eventModifiers onto the given event.

comparing

= anObject
Answer whether the receiver and the argument represent the same events.

MetaClass: EventList class

examples

creationExamples
Select the expressions below one-at-a-time and inspect the results.

randomExample
Create an event list with random data.

randomExample: length
Create an event list with random data.

randomExample: length from: data
Create an event list with random data.

randomSWSSExample
Create an event list with random data appropriate for software sound synthesis.

randomSWSSExample2
Create an event list with random data appropriate for software sound synthesis.

scaleExample2
Answer a scale where the event property types are mixed.

scaleFrom: start to: stop in: dur
Answer an event list with a scale.

sentenceExample
Create an event list for a beautiful sentence.

serialExample: length from: data
Create an event list with serial data.

wordExample
Create an event list for a long word.

class initialization

flush
Erase the shared EventList dictionary and try to clean up all events.

initialize
Initialize the shared EventList dictionary.

storeAll
Write out all event lists.

named constants

named: aName
Answer the named instance from the dictionary or a new EL.

named: aName ifAbsent: theBlock
Answer the named instance from the dictionary or the result of the block.

namedLists
Answer the dictionary of named event lists.

newNamed
Answer the named instance with a temp name.

newNamed: aName
Create and answer a new named (and stored) instance.

nextName
Answer a gensym-type ('te6') event list name for which no EL exists in the dictionary.

instance creation

basicNew: ignored
Create and answer a new default-named instance of me

fromFile: theName
Create and answer a new default un-named (and therefore un-persistent) instance of me

named: myName fromPitches: pitchCollection
Answer an event list made with the given collection of pitches.

named: myName fromSelectors: selArray values: valueArrayArray
Answer an event list made with the given collection of values applied to the given array of selectors.

named: myName fromStartTimes: timeCollection
Answer an event list with the given collection of relative start times.

new
Create and answer a new default-named instance of me

new: ignored
Create and answer a new default-named instance of me

newAnonymous
Create and answer a new default un-named (and therefore un-persistent) instance of me