Inherits from NSObject
Declared in MIKMIDIMappingManager.h

Overview

MIKMIDIMappingManager provides a centralized way to manage an application’s MIDI mappings. It handles both bundled (built in) mapping files, as well as user-customized mappings. It will automatically load both bundled and user mappings from disk. It will also save user mappings to an appropriate location on disk, providing an easy to way to support the ability to import user mappings to an applicaation.

MIKMIDIMappingManager is a singleton.

Tasks

  • + sharedManager

    Used to obtain the shared MIKMIDIMappingManager instance. MIKMIDIMappingManager should not be created directly using +alloc/-init or +new. Rather, the singleton shared instance should always be obtained by calling this method.

  • – mappingsForControllerName:

    Used to obtain the set of all mappings, both user-supplied and bundled, for the controller specified by name. Typically, name is the string obtained by calling [MIKMIDIDevice name].

  • – mappingWithName:

    Used to obtaining a mapping file with a given mapping name.

  • – importMappingFromFileAtURL:overwritingExistingMapping:error:

    Import and load a user-supplied MIDI mapping XML file. This method loads the MIDI mapping file specified by URL and adds it to the set returned by userMappings. The newly imported mapping file is also copied into the application’s user mapping folder so it will be loaded again automatically on subsequent launches.

  • – saveMappingsToDisk

    Saves user mappings to disk. These mappings are currently saved to a folder at //MIDI Mappings. This folder is created automatically if necessary.

  •   bundledMappings

    MIDI mappings loaded from the application’s bundle. These are built in mapping, shipped with the application.

    property
  •   userMappings

    MIDI mappings loaded from the user mappings folder on disk, as well as added at runtime.

    property
  • – addUserMappingsObject:

    Add a new user mapping. The mapping will automatically be saved to a file in the user mappings folder on disk, to be loaded automatically the next time the application is run.

  • – removeUserMappingsObject:

    Remove an existing user mapping. If the mapping is already saved in a file in the user mappings folder on disk, the mapping’s file will be deleted.

  •   mappings

    All mappings, including both user and bundled mappings.

    property

Properties

bundledMappings

@property (nonatomic, strong, readonly) NSSet *bundledMappings
Discussion

MIDI mappings loaded from the application’s bundle. These are built in mapping, shipped with the application.

Declared In

MIKMIDIMappingManager.h

mappings

@property (nonatomic, strong, readonly) NSSet *mappings
Discussion

All mappings, including both user and bundled mappings.

The value of this property is the same as the union of bundledMappings and userMappings

Declared In

MIKMIDIMappingManager.h

userMappings

@property (nonatomic, strong, readonly) NSSet *userMappings
Discussion

MIDI mappings loaded from the user mappings folder on disk, as well as added at runtime.

Declared In

MIKMIDIMappingManager.h

Class Methods

sharedManager

+ (instancetype)sharedManager
Discussion

Used to obtain the shared MIKMIDIMappingManager instance. MIKMIDIMappingManager should not be created directly using +alloc/-init or +new. Rather, the singleton shared instance should always be obtained by calling this method.

Return Value

The shared MIKMIDIMappingManager instance.

Declared In

MIKMIDIMappingManager.h

Instance Methods

addUserMappingsObject:

- (void)addUserMappingsObject:(MIKMIDIMapping *)mapping
Discussion

Add a new user mapping. The mapping will automatically be saved to a file in the user mappings folder on disk, to be loaded automatically the next time the application is run.

Parameters

mapping

An MIKMIDIMapping instance.

Declared In

MIKMIDIMappingManager.h

importMappingFromFileAtURL:overwritingExistingMapping:error:

- (MIKMIDIMapping *)importMappingFromFileAtURL:(NSURL *)URL overwritingExistingMapping:(BOOL)shouldOverwrite error:(NSError **)error
Discussion

Import and load a user-supplied MIDI mapping XML file. This method loads the MIDI mapping file specified by URL and adds it to the set returned by userMappings. The newly imported mapping file is also copied into the application’s user mapping folder so it will be loaded again automatically on subsequent launches.

If shouldOverwrite is YES, and an existing file with the same URL as would be used to save the imported mapping already exists, the existing file is deleted. Otherwise, a unique name is used for the newly imported mapping, preserving both mapping files.

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

Parameters

URL

The fileURL for the mapping file to be imported. Should not be nil.

shouldOverwrite

YES if an existing mapping with the same file name should be overwitten, NO to use a unique file name for the newly imported mapping.

error

Pointer to an NSError used to return information about an error, if any.

Return Value

An MIKMIDIMapping instance for the imported file, or nil if there was an error.

Declared In

MIKMIDIMappingManager.h

mappingWithName:

- (MIKMIDIMapping *)mappingWithName:(NSString *)mappingName
Discussion

Used to obtaining a mapping file with a given mapping name.

Parameters

mappingName

NSString representing the mapping name for the desired mapping.

Return Value

An MIKMIDIMapping instance, or nil if no mapping could be found.

Declared In

MIKMIDIMappingManager.h

mappingsForControllerName:

- (NSSet *)mappingsForControllerName:(NSString *)name
Discussion

Used to obtain the set of all mappings, both user-supplied and bundled, for the controller specified by name. Typically, name is the string obtained by calling [MIKMIDIDevice name].

Parameters

name

The name of the controller for which available mappings are desired.

Return Value

An NSSet containing MIKMIDIMapping instances.

Declared In

MIKMIDIMappingManager.h

removeUserMappingsObject:

- (void)removeUserMappingsObject:(MIKMIDIMapping *)mapping
Discussion

Remove an existing user mapping. If the mapping is already saved in a file in the user mappings folder on disk, the mapping’s file will be deleted.

Parameters

mapping

An MIKMIDIMapping instance.

Declared In

MIKMIDIMappingManager.h

saveMappingsToDisk

- (void)saveMappingsToDisk
Discussion

Saves user mappings to disk. These mappings are currently saved to a folder at //MIDI Mappings. This folder is created automatically if necessary.

This method can be called manually to initiate a save, but is also called automatically anytime a new user mapping is added (via importMappingFromFileAtURL:overwritingExistingMapping:error: or addUserMappingsObject:) as well as upon application termination.

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

Declared In

MIKMIDIMappingManager.h