Inherits from NSObject
Conforms to NSCopying
Declared in MIKMIDIMapping.h

Overview

Overview

MIKMIDIMapping includes represents a complete mapping between a particular hardware controller, and an application’s functionality. Primarily, it acts as a container for MIKMIDIMappingItems, each of which specifies the mapping for a single hardware control.

MIKMIDIMapping can be stored on disk using a straightforward XML format, and includes methods to load and write these XML files. Currently this is only implemented on OS X (see https://github.com/mixedinkey-opensource/MIKMIDI/issues/2 ).

Another class, MIKMIDIMappingManager can be used to manage both application-supplied, and user customized mappings.

Creating Mappings

MIKMIDIMappings can be generated manually, as the XML format is fairly straightforward. MIKMIDI also includes powerful functionality to assist in creating a way for users to easily create their own mappings using a “MIDI learning” interface.

Using Mappings

MIKMIDI does not include built in support for automatically routing messages using a mapping, so a user of MIKMIDI must write some code to make this happen. Typically, this is done by having a single controller in the application be responsible for receiving all incoming MIDI messages. When a MIDI message is received, it can query the MIDI mapping for the mapping item correspoding to the incomding message, then send the command to the mapped responder. Example code for this scenario:

- (void)connectToMIDIDevice:(MIKMIDIDevice *)device {
    MIKMIDIDeviceManager *manager = [MIKMIDIDeviceManager sharedDeviceManager];
    BOOL success = [manager connectInput:source error:error eventHandler:^(MIKMIDISourceEndpoint *source, NSArray *commands) {
        for (MIKMIDICommand *command in commands) {
            [self routeIncomingMIDICommand:command];
        }
    }];

    if (success) self.device = device;
}

- (void)routeIncomingMIDICommand:
{
    MIKMIDIDevice *controller = self.device; // The connected MIKMIDIDevice instance
    MIKMIDIMapping *mapping = [[[MIKMIDIMappingManager sharedManager] mappingsForControllerName:controller.name] anyObject];
    MIKMIDIMappingItem *mappingItem = [[self.MIDIMapping mappingItemsForMIDICommand:command] anyObject];
    if (!mappingItem) return;

    id<MIKMIDIResponder> responder = [NSApp MIDIResponderWithIdentifier:mappingItem.MIDIResponderIdentifier];
    if ([responder respondsToMIDICommand:command]) {
        [responder handleMIDICommand:command];
    }
}

Tasks

Properties

additionalAttributes

@property (nonatomic, copy) NSDictionary *additionalAttributes
Discussion

Optional additional key value pairs, which will be saved as attributes in this mapping’s XML representation. Keys and values must be NSStrings.

Declared In

MIKMIDIMapping.h

bundledMapping

@property (nonatomic, readonly, getter=isBundledMapping) BOOL bundledMapping
Discussion

YES if the receiver was loaded from the application bundle, NO if loaded from user-accessible folder (e.g. Application Support)

Declared In

MIKMIDIMapping.h

controllerName

@property (nonatomic, copy) NSString *controllerName
Discussion

The name of the hardware controller this mapping is for. This should (typically) be the same as the name returned by calling [MIKMIDIDevice name] on the controller’s MIKMIDIDevice instance.

Declared In

MIKMIDIMapping.h

mappingItems

@property (nonatomic, readonly) NSSet *mappingItems
Discussion

All mapping items this mapping contains.

Declared In

MIKMIDIMapping.h

name

@property (nonatomic, copy) NSString *name
Discussion

The name of the MIDI mapping. Currently only used to determine the (default) file name when saving a mapping to disk. If not set, this defaults to the controllerName.

Declared In

MIKMIDIMapping.h

Instance Methods

XMLRepresentation

- (NSXMLDocument *)XMLRepresentation
Discussion

Returns an NSXMLDocument representation of the receiver. The XML document returned by this method can be written to disk.

Note: This method is currently only available on OS X. XMLStringRepresentation can be used on iOS.

Return Value

An NSXMLDocument representation of the receiver.

Declared In

MIKMIDIMapping.h

XMLStringRepresentation

- (NSString *)XMLStringRepresentation
Discussion

Returns an NSString instance containing an XML representation of the receiver. The XML document returned by this method can be written to disk.

Return Value

An NSString containing an XML representation of the receiver.

Declared In

MIKMIDIMapping.h

addMappingItems:

- (void)addMappingItems:(NSSet *)mappingItems
Discussion

Add multiple mapping items to the receiver.

Parameters

mappingItems

An NSSet containing mappings to be added.

Declared In

MIKMIDIMapping.h

addMappingItemsObject:

- (void)addMappingItemsObject:(MIKMIDIMappingItem *)mappingItem
Discussion

Add a single mapping item to the receiver.

Parameters

mappingItem

An MIKMIDIMappingItem instance.

Declared In

MIKMIDIMapping.h

initWithFileAtURL:

- (instancetype)initWithFileAtURL:(NSURL *)url
Discussion

Initializes and returns an MIKMIDIMapping object created from the XML file at url.

Note: This method is currently only available on OS X. See https://github.com/mixedinkey-opensource/MIKMIDI/issues/2

Parameters

url

An NSURL for the file to be read.

Return Value

An initialized MIKMIDIMapping instance, or nil if an error occurred.

Declared In

MIKMIDIMapping.h

initWithFileAtURL:error:

- (instancetype)initWithFileAtURL:(NSURL *)url error:(NSError **)error
Discussion

Initializes and returns an MIKMIDIMapping object created from the XML file at url.

Note: This method is currently only available on OS X. See https://github.com/mixedinkey-opensource/MIKMIDI/issues/2

Parameters

url

An NSURL for the file to be read.

error

If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

Return Value

An initialized MIKMIDIMapping instance, or nil if an error occurred.

Declared In

MIKMIDIMapping.h

mappingItemsForCommandIdentifier:responder:

- (NSSet *)mappingItemsForCommandIdentifier:(NSString *)identifier responder:(id<MIKMIDIMappableResponder>)responder
Discussion

The mapping items that map controls to a specific command identifier supported by a MIDI responder.

Parameters

identifier

An NSString containing one of the responder’s supported command identifiers.

responder

An object that coforms to the MIKMIDIMappableResponder protocol.

Return Value

An NSSet containing MIKMIDIMappingItems for the responder and command identifer, or an empty set if none are found.

See Also

  • [ commandIdentifiers]

Declared In

MIKMIDIMapping.h

mappingItemsForMIDICommand:

- (NSSet *)mappingItemsForMIDICommand:(MIKMIDIChannelVoiceCommand *)command
Discussion

The mapping items for a particular MIDI command (corresponding to a physical control).

This method is typically used to route incoming messages from a controller to the correct mapped responder.

Parameters

command

An an instance of MIKMIDICommand.

Return Value

An NSSet containing MIKMIDIMappingItems for command, or an empty set if none are found.

Declared In

MIKMIDIMapping.h

mappingItemsForMIDIResponder:

- (NSSet *)mappingItemsForMIDIResponder:(id<MIKMIDIMappableResponder>)responder
Discussion

The mapping items that map controls to responder.

This can be used to get mapping items for all commands supported by a responder. It is also possible for multiple physical controls to be mapped to a single command on the same responder.

Parameters

responder

An object that coforms to the MIKMIDIMappableResponder protocol.

Return Value

An NSSet containing MIKMIDIMappingItems for responder, or an empty set if none are found.

Declared In

MIKMIDIMapping.h

removeMappingItems:

- (void)removeMappingItems:(NSSet *)mappingItems
Discussion

Remove multiple mapping items from the receiver.

Parameters

mappingItems

An NSSet containing mappings to be removed.

Declared In

MIKMIDIMapping.h

removeMappingItemsObject:

- (void)removeMappingItemsObject:(MIKMIDIMappingItem *)mappingItem
Discussion

Remove a mapping item from the receiver.

Parameters

mappingItem

An MIKMIDIMappingItem instance.

Declared In

MIKMIDIMapping.h

writeToFileAtURL:error:

- (BOOL)writeToFileAtURL:(NSURL *)fileURL error:(NSError **)error
Discussion

Writes the receiver as an XML file to the specified URL.

Note: This method is currently only available on OS X. See https://github.com/mixedinkey-opensource/MIKMIDI/issues/2

Parameters

fileURL

The URL for the file to be written.

error

If an error occurs, upon returns contains an NSError object that describes the problem. If you are not interested in possible errors, you may pass in NULL.

Return Value

YES if writing the mapping to a file succeeded, NO if an error occurred.

Declared In

MIKMIDIMapping.h