# 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:

• iOS Developer Library: Haptic Feedback (opens new window)

# Properties

# apiName READONLY

Availability

6.0.0

apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

---

# bubbleParent

Availability

6.0.0

bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

---

# 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:

• Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_LIGHT
• Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_MEDIUM
• Titanium.UI.iOS.FEEDBACK_GENERATOR_IMPACT_STYLE_HEAVY

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:

• Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_SELECTION
• Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_IMPACT
• Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_NOTIFICATION

# Methods

# addEventListener

Availability

6.0.0

addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired.

Returns

Type

void

---

# applyProperties

Availability

6.0.0

applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name	Type	Description
props	Dictionary	A dictionary of properties to apply.

Returns

Type

void

---

# fireEvent

Availability

6.0.0

fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name	Type	Description
name	String	Name of the event.
event	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type

void

---

# 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

---

# removeEventListener

Availability

6.0.0

removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to addEventListener.

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