MIKMIDIMappingGenerator

Objective-C

@interface MIKMIDIMappingGenerator : NSObject

Swift

class MIKMIDIMappingGenerator : NSObject

MIKMIDIMappingGenerator is used to map incoming commands from a MIDI device to MIDI responders in an application. It is intended to be used as the basis for a MIDI learning interface, where the application steps through controls/features and for each control, the user simply activates the hardware MIDI control (button, knob, etc.) to map it to that application function.

MIKMIDIMappingGenerator is able to interpret messages coming from a device to determine characteristics of the control sending the messages. This information is stored in the generated mapping for later use in correctly responding to incomding messages from each control. For example, some buttons on MIDI devices send a single message when pressed down, while other button send a message on press, and another on release. MIKMIDIMappingGenerator can determine the behavior for a button during mapping, so that an application knows to expect two messages from the mapped button during later use.

  • Convenience method for creating a mapping generator for a MIKMIDIDevice. The mapping generator will connect to the device’s source endpoint(s) in order to receive MIDI messages from it.

    Declaration

    Objective-C

    + (nonnull instancetype)
    mappingGeneratorWithDevice:(nonnull MIKMIDIDevice *)device
                         error:(NSError *_Nullable *_Nullable)error;

    Parameters

    device

    The MIDI device for which a mapping is to be generated.
    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 MIKMIDIMappingGenerator instance, or nil if an error occurred.

  • Creates and initializes a mapping generator for a MIKMIDIDevice. The mapping generator will connect to the device’s source endpoint(s) in order to receive MIDI messages from it.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithDevice:(nonnull MIKMIDIDevice *)device
                                 error:(NSError *_Nullable *_Nullable)error;

    Swift

    init(device: MIKMIDIDevice, error: NSErrorPointer)

    Parameters

    device

    The MIDI device for which a mapping is to be generated.
    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 MIKMIDIMappingGenerator instance, or nil if an error occurred.

  • Begins mapping a given MIDIResponder. This method returns immediately.

    Declaration

    Objective-C

    - (void)learnMappingForControl:(nonnull id<MIKMIDIMappableResponder>)control
         withCommandIdentifier:(nonnull NSString *)commandID
     requiringNumberOfMessages:(NSUInteger)numMessages
             orTimeoutInterval:(NSTimeInterval)timeout
               completionBlock:
                   (nonnull MIKMIDIMappingGeneratorMappingCompletionBlock)
                       completionBlock;

    Parameters

    control

    The MIDI Responder object to map. Must conform to the MIKMIDIMappableResponder protocol.
    commandID

    The command identifier to be mapped. Must be one of the identifiers returned by the responder’s -commandIdentifiers method.
    numMessages

    The minimum number of messages to receive before immediately mapping the control. Pass 0 for the default.
    timeout

    Time to wait (in seconds) after the last received message before attempting to generate a mapping, or start over. Pass 0 for the default.
    completionBlock

    Block called when mapping is successfully completed. Call -cancelCurrentCommandLearning to cancel a failed mapping.

  • Cancels the mapping previously started by calling -learnMappingForControl:withCommandIdentifier:requiringNumberOfMessages:orTimeoutInterval:completionBlock:.

    Declaration

    Objective-C

    - (void)cancelCurrentCommandLearning;

    Swift

    func cancelCurrentCommandLearning()

  • Temporarily suspends mapping without discarding state. Unlike -cancelCurrentCommandLearning, or -endMapping, mapping can be resumed exactly where it left off by calling -resumeMapping. Incoming MIDI is simply ignored while mapping is suspended.

    Note that if mapping is not currently in progress, this method has no effect.

    Declaration

    Objective-C

    - (void)suspendMapping;

    Swift

    func suspendMapping()

  • Resumes mapping after it was previously suspended using -suspendMapping.

    Note that if mapping was not previously in progress and currently suspended, this has no effect.

    Declaration

    Objective-C

    - (void)resumeMapping;

    Swift

    func resumeMapping()

  • Stops mapping generation, disconnecting from the device.

    Declaration

    Objective-C

    - (void)endMapping;

    Swift

    func endMapping()

  • The delegate for the mapping generator. Can be used to customize certain mapping behavior. Optional.

    The delegate must implement the MIKMIDIMappingGeneratorDelegate protocol.

    Declaration

    Objective-C

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

    Swift

    weak var delegate: MIKMIDIMappingGeneratorDelegate? { get set }

  • The device for which a mapping is being generated. Must not be nil for mapping to work.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) MIKMIDIDevice *device;

    Swift

    var device: MIKMIDIDevice? { get set }

  • The mapping being generated. Assign before mapping starts to modify existing mapping.

    Declaration

    Objective-C

    @property (nonatomic, strong) MIKMIDIMapping *_Nonnull mapping;

    Swift

    var mapping: MIKMIDIMapping { get set }

  • Set this to YES to enable printing diagnostic messages to the console. This is intended to help with eg. debugging trouble mapping specific controllers. The default is NO, ie. logging is disabled.

    Declaration

    Objective-C

    @property (nonatomic, assign, unsafe_unretained, readwrite,
          getter=isDiagnosticLoggingEnabled) BOOL diagnosticLoggingEnabled;

    Swift

    var isDiagnosticLoggingEnabled: Bool { get set }