Class

UIFeedbackGenerator

The abstract superclass for all feedback generators.

Overview

Do not subclass or create instances of this class yourself. Instead, instantiate one of the provided concrete subclasses:

UIImpactFeedbackGenerator. Use impact feedback generators to indicate that an impact has occurred. For example, you might trigger impact feedback when a user interface object collides with something or snaps into place.

UISelectionFeedbackGenerator. Use selection feedback generators to indicate a change in selection.

UINotificationFeedbackGenerator. Use notification feedback generators to indicate successes, failures, and warnings.

Using Feedback Generators

Haptic feedback provides a tactile response, such as a tap, that draws attention and reinforces both actions and events. While many system-provided interface elements (for example, pickers, switches, and sliders) automatically provide haptic feedback, you can use feedback generators to add your own feedback to custom views and controls.

When providing feedback:

  • Always use feedback for its intended purpose. Don’t select a haptic because of the way it feels.

  • The source of the feedback must be clear to the user. For example, the feedback must match a visual change in the user interface, or must be in response to a user action. Feedback should never come as a surprise.

  • Don’t overuse feedback. Overuse can cause confusion and diminish the feedback’s significance.

For additional guidance on when and how to use feedback generators, see Haptic Feedback in iOS Human Interface Guidelines.

To use a feedback generator, the following are required:

  1. Instantiating the Generator

  2. Preparing the Generator (optional)

  3. Triggering Feedback

  4. Releasing the Generator (optional).

Listing 1 demonstrates triggering selection feedback from a pan gesture recognizer.

Listing 1

Triggering selection feedback

var feedbackGenerator : UISelectionFeedbackGenerator? = nil
@IBAction func gestureHandler(_ sender: UIPanGestureRecognizer) {
    
    switch(sender.state) {
    case .began:
        
        // Instantiate a new generator.
        feedbackGenerator = UISelectionFeedbackGenerator()
        
        // Prepare the generator when the gesture begins.
        feedbackGenerator?.prepare()
        
    case .changed:
        
        // Check to see if the selection has changed...
        if  myCustomHasSelectionChangedMethod(translationPoint: sender.translation(in: view)) {
            
            // Trigger selection feedback.
            feedbackGenerator?.selectionChanged()
            
            // Keep the generator in a prepared state.
            feedbackGenerator?.prepare()
        }
        
    case .cancelled, .ended, .failed:
        
        // Release the current generator.
        feedbackGenerator = nil
        
    default:
        // Do Nothing.
        break
    }}

Instantiating the Generator

To create feedback, you must first instantiate one of the UIFeedbackGenerator class’s concrete subclasses (UIImpactFeedbackGenerator, UISelectionFeedbackGenerator, or UINotificationFeedbackGenerator).

Listing 1 instantiates a new UISelectionFeedbackGenerator object whenever a pan gesture begins.

Preparing the Generator

Preparing the generator can reduce latency when triggering feedback. This is particularly important when trying to match feedback to sound or visual cues.

Calling the generator’s prepare() method puts the Taptic Engine in a prepared state. To preserve power, the Taptic Engine stays in this state for only a short period of time (on the order of seconds), or until you next trigger feedback.

Think about when and where you can best prepare your generators. If you call prepare() and then immediately trigger feedback, the system won’t have enough time to get the Taptic Engine into the prepared state, and you may not see a reduction in latency. On the other hand, if you call prepare() too early, the Taptic Engine may become idle again before you trigger feedback.

Listing 1 prepares the generator when the pan gesture begins, and then triggers feedback when the gesture changes.

For more information, see the prepare() method.

Triggering Feedback

Each feedback generator subclass has a unique triggering method. To trigger feedback, call the appropriate method: impactOccurred(), selectionChanged(), or notificationOccurred(_:).

Note that calling these methods does not play haptics directly. Instead, it informs the system of the event. The system then determines whether to play the haptics based on the device, the application’s state, the amount of battery power remaining, and other factors.

For example, haptic feedback is currently played only:

  • On a device with a supported Taptic Engine (iPhone 7 and iPhone 7 Plus).

  • When the app is running in the foreground.

  • When the System Haptics setting is enabled.

As a general rule, trust the system to determine whether it should play feedback. Don't check the device type or app state to conditionally trigger feedback. After you’ve decided how you want to use feedback, always trigger it when the appropriate events occur. The system ignores any requests that it cannot fulfill.

In Listing 1, each time the gesture changes the gesture handler checks to see if the selection has changed. If so, the handler triggers feedback and prepares for the next change.

Releasing the Generator

If you no longer need a prepared generator, remove all references to the generator object and let the system deallocate it. This lets the Taptic Engine return to its idle state.

In Listing 1, the pan gesture recognizer releases its generator when the gesture ends, fails, or is canceled. Assigning nil to the instance variable removes the reference to the old generator. If there are no other references to the generator, the system deallocates it.

Symbols

Instance Methods

func prepare()

Prepares the generator to trigger feedback.

Relationships

Inherits From

Conforms To