1 package net.kreatious.pianoleopard.midi.event;
2
3 import javax.sound.midi.ShortMessage;
4
5 /**
6 * Represents a MIDI message associated with a particular channel and a
7 * timestamp in microseconds.
8 *
9 * @author Jay-R Studer
10 */
11 public abstract class Event {
12 private final long time;
13 private final int channel;
14
15 /**
16 * Constructs a new {@link Event} using the specified channel.
17 *
18 * @param channel
19 * the MIDI channel for this event between 0 and 15 inclusive.
20 * @param time
21 * the time in microseconds when the message occurs.
22 */
23 Event(int channel, long time) {
24 if (channel < 0 || channel > 15) {
25 throw new IllegalArgumentException(channel + " is outside of the valid range [0, 15]");
26 }
27
28 this.channel = channel;
29 this.time = time;
30 }
31
32 /**
33 * Constructs a new {@link Event} using the specified {@link ShortMessage}.
34 *
35 * @param message
36 * the message to extract associated information from
37 * @param time
38 * the time in microseconds when the message occurs.
39 */
40 Event(ShortMessage message, long time) {
41 channel = message.getChannel();
42 this.time = time;
43 }
44
45 /**
46 * Gets the time in microseconds at which this event occurs.
47 *
48 * @return the time in microseconds when this event occurs.
49 */
50 public long getTime() {
51 return time;
52 }
53
54 /**
55 * Gets the channel on which this event occurs.
56 * <p>
57 * The channel value ranges from 0 to 15, inclusive.
58 *
59 * @return the channel on which this event occurs
60 */
61 public int getChannel() {
62 return channel;
63 }
64
65 /**
66 * Gets if this event is an off to on transition.
67 * <p>
68 * Note that an event can transition from off to on multiple times before an
69 * on to off transition occurs.
70 *
71 * @return true if this event marks the start of an interval, false
72 * otherwise
73 */
74 public abstract boolean isOn();
75
76 /**
77 * Gets a slot that uniquely identifies which interval events belong to.
78 * <p>
79 * Equal slots are events occurring for the same channel and key.
80 *
81 * @return a uniquely identifying slot for this event
82 */
83 public abstract Slot getSlot();
84
85 /**
86 * Creates a new off event of the same type and slot with the specified
87 * timestamp.
88 *
89 * @param offTime
90 * the off time of the created event measured in microseconds
91 * @param <T>
92 * the type of the created event, must be the same as the
93 * declaring class.
94 * @return a new event that is off but with the specified timestamp
95 */
96 public abstract <T extends Event> T createOff(long offTime);
97
98 @Override
99 public String toString() {
100 return "Event[" + (isOn() ? "on" : "off") + ", channel: " + channel + ", slot: " + getSlot() + ", time: "
101 + time + "]";
102 }
103 }