MIKMIDIMappingManager

Objective-C

@interface MIKMIDIMappingManager : NSObject

Swift

class MIKMIDIMappingManager : NSObject

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.

  • 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.

    Declaration

    Objective-C

    + (nonnull instancetype)sharedManager;

    Swift

    class func shared() -> Self

    Return Value

    The shared MIKMIDIMappingManager instance.

  • 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].

    Declaration

    Objective-C

    - (nonnull NSSet<MIKMIDIMapping *> *)mappingsForControllerName:
    (nonnull NSString *)name;

    Swift

    func mappings(forControllerName name: String) -> Set<AnyHashable>

    Parameters

    name

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

    Return Value

    An NSSet containing MIKMIDIMapping instances.

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

    Declaration

    Objective-C

    - (nonnull NSSet<MIKMIDIMapping *> *)bundledMappingsForControllerName:
    (nonnull NSString *)name;

    Swift

    func bundledMappings(forControllerName name: String) -> Set<AnyHashable>

    Parameters

    name

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

    Return Value

    An NSSet containing MIKMIDIMapping instances.

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

    Declaration

    Objective-C

    - (nonnull NSSet<MIKMIDIMapping *> *)userMappingsForControllerName:
    (nonnull NSString *)name;

    Swift

    func userMappings(forControllerName name: String) -> Set<AnyHashable>

    Parameters

    name

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

    Return Value

    An NSSet containing MIKMIDIMapping instances.

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

    Declaration

    Objective-C

    - (nonnull NSArray<MIKMIDIMapping *> *)mappingsWithName:
    (nonnull NSString *)mappingName;

    Swift

    func mappings(withName mappingName: String) -> [MIKMIDIMapping]

    Parameters

    mappingName

    NSString representing the mapping name for the desired mapping.

    Return Value

    An array of MIKMIDIMapping instances, or an empty array if no mapping could be found.

  • 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.

    Declaration

    Objective-C

    - (nullable MIKMIDIMapping *)
    importMappingFromFileAtURL:(nonnull NSURL *)URL
    overwritingExistingMapping:(BOOL)shouldOverwrite
                         error:(NSError *_Nullable *_Nullable)error;

    Swift

    func importMappingFromFile(at URL: URL, overwritingExistingMapping shouldOverwrite: Bool) throws -> MIKMIDIMapping

    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.

  • 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.

    Declaration

    Objective-C

    - (void)saveMappingsToDisk;

    Swift

    func saveMappingsToDisk()

  • The delegate of the MIKMIDIMappingManager. Can be used to customize mapping file naming, etc. See the MIKMIDIMappingManagerDelegate protocol for details.

    See

    MIKMIDIMappingManagerDelegate

    Declaration

    Objective-C

    @property (nonatomic, weak) id<MIKMIDIMappingManagerDelegate> _Nullable delegate;

    Swift

    weak var delegate: MIKMIDIMappingManagerDelegate? { get set }

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

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSSet<MIKMIDIMapping *> *_Nonnull bundledMappings;

    Swift

    var bundledMappings: Set<AnyHashable> { get }

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

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSSet<MIKMIDIMapping *> *_Nonnull userMappings;

    Swift

    var userMappings: Set<AnyHashable> { get }

  • 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.

    Declaration

    Objective-C

    - (void)addUserMappingsObject:(nonnull MIKMIDIMapping *)mapping;

    Swift

    func addUserMappingsObject(_ mapping: MIKMIDIMapping)

    Parameters

    mapping

    An MIKMIDIMapping instance.

  • 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.

    Declaration

    Objective-C

    - (void)removeUserMappingsObject:(nonnull MIKMIDIMapping *)mapping;

    Swift

    func removeUserMappingsObject(_ mapping: MIKMIDIMapping)

    Parameters

    mapping

    An MIKMIDIMapping instance.

  • All mappings, including both user and bundled mappings.

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

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) NSSet<MIKMIDIMapping *> *_Nonnull mappings;

    Swift

    var mappings: Set<AnyHashable> { get }

Deprecated

  • Deprecated

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

    @deprecated Deprecated. Use -mappingsWithName: instead.

    Declaration

    Objective-C

    - (nullable MIKMIDIMapping *)mappingWithName:(nonnull NSString *)mappingName;

    Swift

    func mapping(withName mappingName: String) -> MIKMIDIMapping?

    Parameters

    mappingName

    NSString representing the mapping name for the desired mapping.

    Return Value

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