Class

CHHapticEngine

An object that manages your app's requests to play haptic patterns.

Declaration

@interface CHHapticEngine : NSObject

Overview

If you want your app to play custom haptics, you need to create a haptic engine. The haptic engine establishes the connection between your app and the underlying device hardware. Even though you can define a haptic pattern without an engine, you need the engine to play that pattern.

A dictionary defines a pattern, from which the haptic engine creates a pattern player for playing the haptic.

Even though your app makes a request through the haptic engine, the operating system could still override the request with system services, like haptics from system notifications.

Prepare Your App To Play Haptics

To prepare your app to play haptics, follow these steps, as demonstrated in the code below:

  1. Create an instance of a haptic engine and maintain ownership through an instance variable or strong property, so it doesn't go out of scope while the haptic is playing.

  2. Call the haptic engine's startWithCompletionHandler: for an asynchronous start, or startAndReturnError: to start the engine synchronously (immediately).

  3. Stop the engine by calling stopWithCompletionHandler: when your app finishes haptic playback.

// Create an error variable through which the engine returns error information.
NSError* error = nil;

// (1.) Create an instance of a haptic engine.
self.hapticEngine = [[CHHapticEngine alloc] initAndReturnError:&error];

// (2.) Start the haptic engine.
[self.hapticEngine startAndReturnError:&error];

// (3.) Stop the engine.
[self.hapticEngine stopWithCompletionHandler:^(NSError* error){
    // Insert code to call after engine stops.
}];

Although it's possible to create content—CHHapticPattern instances—independent of a CHHapticEngine, your app must use an engine to play that content.

Topics

Initializing a Haptic Engine

- initAndReturnError:

Creates an instance of the haptic engine.

- initWithAudioSession:error:

Creates a haptic engine from an audio session.

Starting and Stopping the Haptic Engine

- startAndReturnError:

Synchronously starts the haptic engine.

- startWithCompletionHandler:

Asynchronously starts the haptic engine and executes the completion handler once the engine has started.

- stopWithCompletionHandler:

Asynchronously stops the haptic engine and executes the completion handler once the engine has stopped.

CHHapticCompletionHandler

A typealias for the block that the engine calls after starting or stopping.

Creating Haptic Pattern Players

Factory methods for creating player objects for haptic playback.

CHHapticPatternPlayer

A protocol that defines a standard pattern player capable of playing haptic patterns with fixed parameters.

- createPlayerWithPattern:error:

Creates a standard haptic pattern player from a haptic pattern.

CHHapticAdvancedPatternPlayer

A protocol that defines an advanced pattern player capable of looping, seeking, pausing, and resuming haptic playback.

- createAdvancedPlayerWithPattern:error:

Creates an advanced haptic pattern player from a haptic pattern.

Modifying Playback Properties

playsHapticsOnly

A Boolean that indicates whether the haptic engine ignores audio events.

isMutedForAudio

A Boolean that indicates whether audio is muted for the haptic engine.

isMutedForHaptics

A Boolean that indicates whether haptics is muted for the haptic engine.

Playing a Pattern

- playPatternFromURL:error:

Plays a plist pattern from the specified URL.

- playPatternFromData:error:

Plays a plist pattern from the specified data.

Registering Audio Resources

- registerAudioResource:options:error:

Registers an external audio file for use as a custom waveform.

- unregisterAudioResource:error:

Unregisters a previously registered external audio file.

CHHapticAudioResourceID

A type alias used to register an ID for a custom audio resource.

Monitoring Finished Playback

- notifyWhenPlayersFinished:

Notifies you when all haptic pattern players have finished playing their haptic patterns.

CHHapticEngineFinishedHandler

A type alias for a completion handler to execute after finishing haptic playback.

CHHapticEngineFinishedAction

Possible actions to take after the haptic engine finishes execution.

Handling Haptic Engine Resets

resetHandler

A block that the haptic engine calls after recovering from a haptic server error.

CHHapticEngineResetHandler

A typealias for the block that the haptic engine calls after being reset.

Handling Haptic Engine Stoppages

stoppedHandler

A block that the haptic engine calls when it stops due to external causes.

CHHapticEngineStoppedHandler

A typealias for the block that the haptic engine calls after it stops due to external causes.

CHHapticEngineStoppedReason

An enumeration of possible reasons the haptic engine stopped running.

Getting the Current Media Time

currentTime

The absolute time, in seconds, to use for scheduling haptic and audio events.

CHHapticTimeImmediate

A time constant used to schedule a command immediately.

Querying System Capabilities

+ capabilitiesForHardware

Returns a device capability object that specifies the device's haptic support and limitations.

CHHapticDeviceCapability

A protocol that defines haptics and audio capabilities of a device.

CHHapticParameterAttributes

A protocol for providing default, mininum, and maximum values of a parameter.

- attributesForDynamicParameter:error:

Requests the haptic device's attributes for a dynamic parameter.

Required.

Managing Power

autoShutdownEnabled

Opt in for auto start and auto stop.

Relationships

Inherits From

See Also

Essentials

Preparing Your App to Play Haptics

Set up your app to play haptics.

Playing a Single-Tap Haptic Pattern

Create and play a transient haptic pattern from a dictionary literal inline.

CHHapticPattern

An object representing a haptic waveform.