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.

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

Extends: Titanium.Proxy · Since: 6.0.0 · Platforms: iphone

Properties

apiName

extended

3.2.0

3.2.0

3.2.0

9.2.0

Type: 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, Button
returns Ti.UI.Button.

bubbleParent

extended

3.0.0

3.0.0

3.0.0

9.2.0

Type: 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.

lifecycleContainer

extended

3.6.0

Type: Titanium.UI.Window, Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.

style

creation only

0.9

0.9

0.9

9.2.0

Type: Number

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

type

creation only

0.9

0.9

0.9

9.2.0

Type: Number

The type of feedback generator you want to create.

Methods

addEventListener

extended

0.9

0.9

0.9

9.2.0

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

Parameters:

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

applyProperties

extended

3.0.0

3.0.0

3.0.0

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	Summary	Optional
props	Dictionary	A dictionary of properties to apply.	No

fireEvent

extended

0.9

0.9

0.9

9.2.0

Fires a synthesized event to any registered listeners.

Parameters:

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

impactOccurred

0.9

0.9

0.9

9.2.0

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
Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_IMPACT.

notificationOccurred

0.9

0.9

0.9

9.2.0

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
Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_NOTIFICATION. The single argument provided is one of the

Parameters:

Name	Type	Summary	Optional
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.	No

prepare

0.9

0.9

0.9

9.2.0

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.

removeEventListener

extended

0.9

0.9

0.9

9.2.0

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	Summary	Optional
name	String	Name of the event.	No
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to addEventListener.	No

selectionChanged

0.9

0.9

0.9

9.2.0

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
Titanium.UI.iOS.FEEDBACK_GENERATOR_TYPE_SELECTION.