Titanium Mobile

# Titanium.UI.iOS.FeedbackGenerator

The feedback generator API is introduced in iOS 10 to handle the haptic feedback when using an iPhone 7 or later devices.

Availability
6.0.0
Extends
Titanium.Proxy

# Overview

On supported devices, haptics provide a way to physically engage users with tactile feedback that gets attention and reinforces actions. Some system-provided interface elements, such as pickers, switches, and sliders, automatically provide haptic feedback as users interact with them. Your app can also ask the system to generate different types of haptic feedback. iOS manages the strength and behavior of this feedback.

There are three different kind of feedback generators that can be used for different interaction scenarios:

  1. Selection Feedback: Indicates that a task or action, such as depositing a check or unlocking a vehicle, has completed, failed, or produced a warning of some kind. This feedback type can be used when specifying the Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_SELECTION constant in the type property of the feedback generator.

  2. Impact Feedback: Provides a physical metaphor that complements the visual experience. For example, the user might feel a thud when a view slides into place or two objects collide. This feedback type can be used when specifying the Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_IMPACT constant in the type property of the feedback generator. Note that if you use this generator type, you also have to specify the style property that can be one of the Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_LIGHT, Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_MEDIUM or Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_HEAVY constants.

  3. Notification Feedback: Indicates that the selection is actively changing. For example, the user feels light taps while scrolling a picker wheel. This feedback is intended for communicating movement through a series of discrete values, not making or confirming a selection. This feedback type can be used when using the Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_NOTIFICATION constant in the type property of the feedback generator.

Example When clicking a button you should trigger an impact feedback as displayed below.

var generator = Ti.UI.iOS.createFeedbackGenerator({
  type: Ti.UI.iOS.FEEDBACK_GENERATOR_TYPE_IMPACT,
  style: Ti.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_LIGHT
});
generator.impactOccurred();

We're not using generator.prepare() here because we're triggering the feedback immediately. When you know a feedback generator is triggered within a couple seconds you should use prepare() to know for sure the timing is correct.

See also:

# Properties

# style CREATION ONLY

Availability
6.0.0
style :Number

The style of the feedback generator you want to create. This property is only required when using FEEDBACK_GENERATOR_TYPE_IMPACT.

This API can be assigned the following constants:

Default: Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_MEDIUM

# type CREATION ONLY

Availability
6.0.0
type :Number

The type of feedback generator you want to create.

This API can be assigned the following constants:

# Methods

# impactOccurred

Availability
6.0.0
impactOccurred() → void

Used to trigger a haptic feedback after an impact occurred.

Note that this method can only be used if the feeback generator type is set to FEEDBACK_GENERATOR_TYPE_IMPACT.

Returns

Type
void

# notificationOccurred

Availability
6.0.0
notificationOccurred(notificationType) → void

Used to trigger a haptic feedback after a notification has been received.

Note that this method can only be used if the feeback generator type is set to FEEDBACK_GENERATOR_TYPE_NOTIFICATION. The single argument provided is one of the

Parameters

Name Type Description
notificationType Number

The type of the notification to manage the peculiarity of the haptic feedback. If this parameter is not specified, an error will be thrown.

Returns

Type
void

# prepare

Availability
6.0.0
prepare() → void

Used to prepare the haptic sensor for the upcoming interaction with it.

Apple recommends to use this method before calling one of the selectionChanged, impactOccurred or notificationOccurred methods to reduce a possible latency.

Returns

Type
void

# selectionChanged

Availability
6.0.0
selectionChanged() → void

Used to trigger a haptic feedback after a selection has been made.

Note that this method can only be used if the feeback generator type is set to FEEDBACK_GENERATOR_TYPE_SELECTION.

Returns

Type
void

Contents