MIKMIDIMapping

Objective-C

@interface MIKMIDIMapping : NSObject <NSCopying>

Swift

class MIKMIDIMapping : NSObject, NSCopying

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];
    }
}

See

MIKMIDIMappingManager

See

MIKMIDIMappingGenerator


                    
                    
                    -initWithFileAtURL:error:

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

Declaration

Objective-C

- (nullable instancetype)initWithFileAtURL:(nonnull NSURL *)url
                                     error:(NSError *_Nullable *_Nullable)error;

Swift

init(fileAt url: URL, error: ()) throws

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.


                    
                    
                    +userMappingFromBundledMapping:

Creates and initializes an MIKMIDIMapping object that is the same as the passed in bundled mapping
but with isBundledMapping set to NO.

- parameter: bundledMapping The bundled mapping you would like to make a user mapping copy of.

- returns: An initialized MIKMIDIMapping instance that is the same as the passed in mapping but
with isBundledMapping set to NO.

Declaration

Objective-C

+ (nonnull instancetype)userMappingFromBundledMapping:
    (nonnull MIKMIDIMapping *)bundledMapping;

Swift

class func userMapping(fromBundledMapping bundledMapping: MIKMIDIMapping) -> Self

-XMLRepresentation
Deprecated

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. @deprecated This method is deprecated on OS X. Use -XMLStringRepresentation instead.

See

-writeToFileAtURL:error:
Declaration
Objective-C

- (nonnull NSXMLDocument *)XMLRepresentation;
Swift

func xmlRepresentation() -> XMLDocument
Return Value

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

See

-writeToFileAtURL:error:
Declaration
Objective-C

- (nullable NSString *)XMLStringRepresentation;
Swift

func xmlStringRepresentation() -> String?
Return Value

An NSString containing an XML representation of the receiver, or nil if an error occurred.


                    
                    
                    -writeToFileAtURL:error:

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

Declaration

Objective-C

- (BOOL)writeToFileAtURL:(nonnull NSURL *)fileURL
                   error:(NSError *_Nullable *_Nullable)error;

Swift

func writeToFile(at fileURL: URL) throws

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.


                    
                    
                    -mappingItemsForMIDIResponder:

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.

Declaration

Objective-C

- (nonnull NSSet<MIKMIDIMappingItem *> *)mappingItemsForMIDIResponder:
    (nonnull id<MIKMIDIMappableResponder>)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.


                    
                    
                    -mappingItemsForCommandIdentifier:responder:

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

See

-[ commandIdentifiers]

See

-mappingItemsForCommandIdentifier:responderWithIdentifier:

Declaration

Objective-C

- (nonnull NSSet<MIKMIDIMappingItem *> *)
    mappingItemsForCommandIdentifier:(nonnull NSString *)commandID
                           responder:
                               (nonnull id<MIKMIDIMappableResponder>)responder;

Parameters

`commandID`	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.


                    
                    
                    -mappingItemsForCommandIdentifier:responderWithIdentifier:

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

See

-[ commandIdentifiers]

See

-mappingItemsForCommandIdentifier:responder:

Declaration

Objective-C

- (nonnull NSSet<MIKMIDIMappingItem *> *)
    mappingItemsForCommandIdentifier:(nonnull NSString *)commandID
             responderWithIdentifier:(nonnull NSString *)responderID;

Swift

func mappingItems(forCommandIdentifier commandID: String, responderWithIdentifier responderID: String) -> Set<AnyHashable>

Parameters

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

Return Value

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


                    
                    
                    -mappingItemsForMIDICommand:

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.

Declaration

Objective-C

- (nonnull NSSet<MIKMIDIMappingItem *> *)mappingItemsForMIDICommand:
    (nonnull MIKMIDIChannelVoiceCommand *)command;

Swift

func mappingItems(forMIDICommand command: MIKMIDIChannelVoiceCommand) -> Set<AnyHashable>

Parameters


                                command

An an instance of MIKMIDICommand.

Return Value

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

name
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.
Declaration
Objective-C

@property (nonatomic, copy) NSString *_Nonnull name;
Swift

var name: String { get set }
controllerName
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.
Declaration
Objective-C

@property (nonatomic, copy) NSString *_Nonnull controllerName;
Swift

var controllerName: String { get set }
bundledMapping
YES if the receiver was loaded from the application bundle, NO if loaded from user-accessible folder (e.g. Application Support)
Declaration
Objective-C

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

var isBundledMapping: Bool { get }
additionalAttributes
Optional additional key value pairs, which will be saved as attributes in this mapping’s XML representation. Keys and values must be NSStrings.
Declaration
Objective-C

@property (nonatomic, copy, nullable) NSDictionary *additionalAttributes;
Swift

var additionalAttributes: [AnyHashable : Any]? { get set }


                    
                    
                    mappingItems

All mapping items this mapping contains.

Declaration

Objective-C

@property (nonatomic, readonly) NSSet<MIKMIDIMappingItem *> *_Nonnull mappingItems;

Swift

var mappingItems: Set<AnyHashable> { get }


                    
                    
                    -addMappingItemsObject:

Add a single mapping item to the receiver.

Declaration

Objective-C

- (void)addMappingItemsObject:(nonnull MIKMIDIMappingItem *)mappingItem;

Swift

func addItemsObject(_ mappingItem: MIKMIDIMappingItem)

Parameters


                                mappingItem

An MIKMIDIMappingItem instance.


                    
                    
                    -addMappingItems:

Add multiple mapping items to the receiver.

Declaration

Objective-C

- (void)addMappingItems:(nonnull NSSet<MIKMIDIMappingItem *> *)mappingItems;

Swift

func add(_ mappingItems: Set<AnyHashable>)

Parameters


                                mappingItems

An NSSet containing mappings to be added.


                    
                    
                    -removeMappingItemsObject:

Remove a mapping item from the receiver.

Declaration

Objective-C

- (void)removeMappingItemsObject:(nonnull MIKMIDIMappingItem *)mappingItem;

Swift

func removeItemsObject(_ mappingItem: MIKMIDIMappingItem)

Parameters


                                mappingItem

An MIKMIDIMappingItem instance.


                    
                    
                    -removeMappingItems:

Remove multiple mapping items from the receiver.

Declaration

Objective-C

- (void)removeMappingItems:(nonnull NSSet<MIKMIDIMappingItem *> *)mappingItems;

Swift

func removeMappingItems(_ mappingItems: Set<AnyHashable>)

Parameters


                                mappingItems

An NSSet containing mappings to be removed.

Deprecated


                    
                    
                    -initWithFileAtURL:

Deprecated

@deprecated Use -initWithFileAtURL:error: instead. Initializes and returns an MIKMIDIMapping object created from the XML file at url.

See

-initWithFileAtURL:error:

Declaration

Objective-C

- (nullable instancetype)initWithFileAtURL:(nonnull NSURL *)url;

Swift

init?(fileAt url: URL)

Parameters

url

An NSURL for the file to be read.

Return Value

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