Inherits from NSObject
Conforms to NSCopying
Declared in MIKMIDIEvent.h

Overview

In MIKMIDI, MIDI events are objects. Specifically, they are instances of MIKMIDIEvent or one of its subclasses. MIKMIDIEvent’s subclasses each represent a specific type of MIDI event, for example, note events will be instances of MIKMIDINoteEvent. MIKMIDIEvent includes properties for getting information and data common to all MIDI events. Its subclasses implement additional method and properties specific to messages of their associated type.

MIKMIDIEvent is also available in mutable variants, most useful for creating events to be sent out by your application.

To create a new event, typically, you should use midiEventWithTimeStamp:eventType:data:(NSData *)data

Subclass MIKMIDIEvent

Support for the various MIDI event types is provided by type-specific subclasses of MIKMIDIEvent. For example, note events are represented using MIKMIDINoteEvent.

To support a new event type, you should create a new subclass of MIKMIDIEvent (and please consider contributing it to the main MIKMIDI repository!). If you implement this subclass according to the rules explained below, it will automatically be used to represent MIDI events matching its MIDI event type.

To successfully subclass MIKMIDIEvent, you must override at least the following methods:

  • +supportsMIKMIDIEventType: - Return YES when passed the MIKMIDIEventType value your subclass supports.
  • +immutableCounterPartClass - Return the subclass itself (eg. return [MIKMIDINewTypeEvent class];)
  • +mutableCounterPartClass - Return the mutable counterpart class (eg. return [MIKMIDIMutableNewTypeEvent class;])

Optionally, override -additionalEventDescription to provide an additional, type-specific description string.

You must also implement +load and call [MIKMIDIEvent registerSubclass:self] to register your subclass with the MIKMIDIEvent machinery.

When creating a subclass of MIKMIDIEvent, you should also create a mutable variant which is itself a subclass of your type-specific MIKMIDIEvent subclass. The mutable subclass should override +isMutable and return YES.

If your subclass adds additional properties, beyond those supported by MIKMIDIEvent itself, those properties should only be settable on instances of the mutable variant class. The preferred way to accomplish this is to implement the setters on the immutable, base subclass. In their implementations, check to see if self is mutable, and if not, raise an exception. Use the following line of code:

    if (![[self class] isMutable]) return MIKMIDI_RAISE_MUTATION_ATTEMPT_EXCEPTION;

For a straightforward example of a MIKMIDIEvent subclass, see MIKMIDINoteEvent.

Tasks

Other Methods

  •   eventType

    The MIDI event type. See MusicPlayer.h for a list of possible values.

    property
  •   channel

    The channel for the MIDI event.

    property
  •   timeStamp

    The timeStamp of the MIDI event. When used in a MusicSequence of type kMusicSequenceType_Beats a timeStamp of 1 equals one quarter note. See the MusicSequence Reference for more information.

    property
  •   data

    The data representing the event. The actual type of stored data will vary by subclass. For example, in MIKMIDINoteEvent the data property’s bytes are of type MIDINoteMessage.

    property
  • + midiEventWithTimeStamp:eventType:data:

    Convenience method for creating a new MIKMIDIEvent instance from an NSData instance. For event types for which there is a specific MIKMIDIEvent subclass, an instance of the appropriate subclass will be returned.

Extension Methods

  • + registerSubclass:

    Registers a subclass of MIKMIDIEvent. Registered subclasses will be instantiated and returned by +[MIKMIDIEvent ] for events they support.

  • + supportsMIKMIDIEventType:

    Subclasses of MIKMIDIEvent must override this method, and return YES for any MIKMIDIEventType values they support. MIKMIDIEvent uses this method to determine which subclass to use to represent a particular MIDI event type.

  • + immutableCounterpartClass

    The immutable counterpart class of the receiver.

  • + mutableCounterpartClass

    The mutable counterpart class of the receiver.

  • + isMutable

    Mutable subclasses of MIKMIDIEvent must override this method and return YES. MIKMIDIEvent itself implements this and returns NO, so immutable subclasses need not override this method.

  •   internalData

    This is the property used internally by MIKMIDIEvent to store the raw data for a MIDI packet. It is essentially the mutable backing store for MIKMIDIEvent’s data property. Subclasses may set it. When mutating it, subclasses should manually call -will/didChangeValueForKey for the internalData key path.

    property
  •   metaData property
  • – additionalEventDescription

    Additional description string to be appended to basic description provided by [MIKMIDIEvent description]. Subclasses of MIKMIDIEvent can override this to provide a additional description information.

Properties

channel

@property (nonatomic, readonly) UInt8 channel
Discussion

The channel for the MIDI event.

Declared In

MIKMIDIEvent.h

data

@property (nonatomic, readonly) NSData *data
Discussion

The data representing the event. The actual type of stored data will vary by subclass. For example, in MIKMIDINoteEvent the data property’s bytes are of type MIDINoteMessage.

Declared In

MIKMIDIEvent.h

eventType

@property (nonatomic, readonly) MusicEventType eventType
Discussion

The MIDI event type. See MusicPlayer.h for a list of possible values.

Declared In

MIKMIDIEvent.h

internalData

@property (nonatomic, strong, readwrite) NSMutableData *internalData
Discussion

This is the property used internally by MIKMIDIEvent to store the raw data for a MIDI packet. It is essentially the mutable backing store for MIKMIDIEvent’s data property. Subclasses may set it. When mutating it, subclasses should manually call -will/didChangeValueForKey for the internalData key path.

Declared In

MIKMIDIEvent_SubclassMethods.h

metaData

@property (nonatomic, strong, readwrite) NSData *metaData

timeStamp

@property (nonatomic, readonly) MusicTimeStamp timeStamp
Discussion

The timeStamp of the MIDI event. When used in a MusicSequence of type kMusicSequenceType_Beats a timeStamp of 1 equals one quarter note. See the MusicSequence Reference for more information.

Declared In

MIKMIDIEvent.h

Class Methods

immutableCounterpartClass

+ (Class)immutableCounterpartClass
Discussion

The immutable counterpart class of the receiver.

Return Value

A class object for the immutable counterpart class of the receiver, or self if the receiver is the immutable class in the pair.

Declared In

MIKMIDIEvent_SubclassMethods.h

isMutable

+ (BOOL)isMutable
Discussion

Mutable subclasses of MIKMIDIEvent must override this method and return YES. MIKMIDIEvent itself implements this and returns NO, so immutable subclasses need not override this method.

Return Value

YES if the receiver is a mutable MIKMIDIEvent subclass, NO otherwise.

Declared In

MIKMIDIEvent_SubclassMethods.h

midiEventWithTimeStamp:eventType:data:

+ (instancetype)midiEventWithTimeStamp:(MusicTimeStamp)timeStamp eventType:(MusicEventType)eventType data:(NSData *)data
Discussion

Convenience method for creating a new MIKMIDIEvent instance from an NSData instance. For event types for which there is a specific MIKMIDIEvent subclass, an instance of the appropriate subclass will be returned.

Parameters

timeStamp

The MusicTimeStamp for the event.

eventType

The MusicEventType of the event.

data

The data representing the event.

Return Value

For supported event types, an initialized MIKMIDIEvent subclass. Otherwise, an instance of MIKMIDIEvent itself. nil if there is an error.

Declared In

MIKMIDIEvent.h

mutableCounterpartClass

+ (Class)mutableCounterpartClass
Discussion

The mutable counterpart class of the receiver.

Return Value

A class object for the mutable counterpart class of the receiver, or self if the receiver is the mutable class in the pair.

Declared In

MIKMIDIEvent_SubclassMethods.h

registerSubclass:

+ (void)registerSubclass:(Class)subclass
Discussion

Registers a subclass of MIKMIDIEvent. Registered subclasses will be instantiated and returned by +[MIKMIDIEvent ] for events they support.

Typically this method should be called in the subclass’s +load method.

Note: If two subclasses support the same event type, as determined by calling +supportsMIDIEvent: which one is used is undefined.

Parameters

subclass

A subclass of MIKMIDIEvent.

Declared In

MIKMIDIEvent_SubclassMethods.h

supportsMIKMIDIEventType:

+ (BOOL)supportsMIKMIDIEventType:(MIKMIDIEventType)type
Discussion

Subclasses of MIKMIDIEvent must override this method, and return YES for any MIKMIDIEventType values they support. MIKMIDIEvent uses this method to determine which subclass to use to represent a particular MIDI event type.

Parameters

type

An MIKMIDIEventType value.

Return Value

YES if the subclass supports type, NO otherwise.

Declared In

MIKMIDIEvent_SubclassMethods.h

Instance Methods

additionalEventDescription

- (NSString *)additionalEventDescription
Discussion

Additional description string to be appended to basic description provided by [MIKMIDIEvent description]. Subclasses of MIKMIDIEvent can override this to provide a additional description information.

Return Value

A string to be appended to MIKMIDIEvent’s basic description.

Declared In

MIKMIDIEvent_SubclassMethods.h