# Titanium.UI.iOS.ApplicationShortcuts

The Home screen quick actions API is for adding shortcuts to your app icon that anticipate and accelerate a user's interaction with your app.

Availability

5.1.0

Extends

Titanium.Proxy

DEPRECATED SINCE 9.1.0

Use Titanium.UI.Shortcut instead.

# Overview

3D Touch gives iOS 9 users an additional interaction dimension. On supported devices, people can quickly choose app-specific actions from the Home screen by pressing on the app icon. The pressing of an application shortcut will then fire the shortcutitemclick Titanium.App.iOS event.

There are static and dynamic shortcuts to differentiate:

Static: Can be set in the <ios> section of the tiapp.xml before launching the app.
Dynamic: Can be set in the app to offer a dynamic behavior at runtime.

Here is an example how to create static application shortcuts in the tiapp.xml:

<ti:app>
    <!-- ... -->
    <ios>
        <plist>  
            <dict>
            <key>UIApplicationShortcutItems</key>
            <array>
                <dict>
                    <key>UIApplicationShortcutItemIconType</key>
                    <string>UIApplicationShortcutIconTypeSearch</string>
                    <key>UIApplicationShortcutItemTitle</key>
                    <string>My title</string>
                    <key>UIApplicationShortcutItemSubtitle</key>
                    <string>My subtitle</string>
                    <key>UIApplicationShortcutItemType</key>
                    <string>my_identifier</string>
                    <key>UIApplicationShortcutItemUserInfo</key>
                    <dict/>
                </dict>
            </array>
            </dict> 
        </plist> 
    </ios>
    <!-- ... -->
</ti:app>

Static shortcuts can be translated in the i18n/<language>/app.xml file. Dynamic shortcuts can be translated by using the methods described in the Wiki.

To use this feature make sure you have a 3D Touch compatible device running iOS 9 or later. To check for the feature, use the Titanium.UI.iOS.forceTouchSupported property. You cannot test 3D touch on the iOS simulator.

# Examples

# Full example (get shortcuts, add shortcuts, remove shortcuts, check shortcuts).

Ti.App.iOS.addEventListener("shortcutitemclick", function (e) {
    Ti.API.info("shortcutitemclick Event Fired");
    Ti.API.info("event payload:" + JSON.stringify(e));
});

var win = Titanium.UI.createWindow({
    title: 'Test', backgroundColor: '#fff', layout: "vertical"
});

var btn1 = Ti.UI.createButton({
    top: 50, height: 45, title: "Add Contact Us Application Shortcut"
});
win.add(btn1);

btn1.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    appShortcuts.addDynamicShortcut({
        identifier: "contact_us",
        title: "Contact Us",
        subtitle: "Tap to reach us",
        icon: Ti.UI.iOS.SHORTCUT_ICON_TYPE_ADD,
        userInfo: {
            infoKey: "contact_us"
        }
    });
});

var btn2 = Ti.UI.createButton({
    top: 10, height: 45, title: "Remove Contact Us Application Shortcut"
});
win.add(btn2);

btn2.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    appShortcuts.removeDynamicShortcut("contact_us");
});

var btn3 = Ti.UI.createButton({
    top: 10, height: 45, title: "Count Dynamic App Shortcuts"
});
win.add(btn3);

btn3.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    var shortcuts = appShortcuts.listDynamicShortcuts();
    Ti.API.info("Dynamic App Shortcut count:" + shortcuts.length);
    Ti.API.info("Dynamic App Shortcut as JSON:" + JSON.stringify(shortcuts));
});

var btn4 = Ti.UI.createButton({
    top: 10, height: 45, title: "Count Static App Shortcuts"
});
win.add(btn4);

btn4.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    var shortcuts = appShortcuts.listStaticShortcuts();
    Ti.API.info("Static App Shortcut count:" + shortcuts.length);
    Ti.API.info("Static App Shortcut as JSON:" + JSON.stringify(shortcuts));
});

var btn5 = Ti.UI.createButton({
    top: 10, height: 45, title: "Dynamic Shortcut Exists?"
});
win.add(btn5);

btn5.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    var exists = appShortcuts.dynamicShortcutExists("contact_us");
    var msg = (exists) ? "Icon exists" : "Sorry isn't there";
    alert(msg);
});

var btn6 = Ti.UI.createButton({
    top: 10, height:45, title:"Remove All Dynamic Shortcuts"
});
win.add(btn6);

btn6.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    appShortcuts.removeAllDynamicShortcuts();
});

var btn7 = Ti.UI.createButton({
    top: 10, height: 45, title: "Get shortcut by identifier \"contact_us\""
});
win.add(btn7);

btn7.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    var shortcut = appShortcuts.getDynamicShortcut("contact_us");
    alert(shortcut);
});

win.open();

# Add a Titanium.Contact.Person as icon.

Ti.App.iOS.addEventListener("shortcutitemclick", function (e) {
    Ti.API.info("shortcutitemclick Event Fired");
    Ti.API.info("person:" + JSON.stringify(e.userInfo.person));
});

var win = Titanium.UI.createWindow({
    title: 'Test', backgroundColor: '#fff', layout: "vertical"
});

var btn1 = Ti.UI.createButton({
    top: 50, height: 45, title: "Add Ti.Contacts Application Shortcut"
});
win.add(btn1);

btn1.addEventListener("click", function () {
    if (!Ti.Contacts.hasContactsPermissions()) {
        Ti.Contacts.requestContactsPermissions(function (e) {
            if (e.success) {
                createShortcut();
            }
        })
    } else {
        createShortcut();
    }
});

var btn2 = Ti.UI.createButton({
    top: 10, height: 45, title: "Remove Ti.Contacts Application Shortcut"
});
win.add(btn2);

btn2.addEventListener("click", function () {
    var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
    appShortcuts.removeDynamicShortcut("contact_us");
});

function createShortcut() {
    Ti.Contacts.showContacts({
        selectedPerson: function(e) {
            var person = e.person;

            var appShortcuts = Ti.UI.iOS.createApplicationShortcuts();
            appShortcuts.addDynamicShortcut({
                identifier: "contact_us",
                title: person.fullName,
                subtitle: "Tap to call",
                icon: person,
                userInfo: {
                    person: {
                        firstName: person.firstName,
                        lastName: person.lastName
                    }
                }
            });
        }
    });
}

win.open();

# Properties

# apiName READONLY

Availability

5.1.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

5.1.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

# Methods

# addDynamicShortcut

Availability

5.1.0

addDynamicShortcut(params) → void

Creates a new dynamic application shortcut item.

Parameters

Name	Type	Description
`params`	ShortcutParams	The parameters used when creating a dynamic shortcut.

Returns

Type: void

# addEventListener

Availability

5.1.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

5.1.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

# dynamicShortcutExists

Availability

5.1.0

dynamicShortcutExists(identifier) → Boolean

Returns true or false depending if the provided shortcut object already exists.

Parameters

Name	Type	Description
`identifier`	String	Checks if the dynamic application shortcut item identified by the `identifier` exists.

Returns

Type: Boolean

# fireEvent

Availability

5.1.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

# getDynamicShortcut

Availability

5.1.0

getDynamicShortcut(identifier) → ShortcutParams

Gets the dynamic application shortcut item identified by the identifier.

Parameters

Name	Type	Description
`identifier`	String	Use the `identifier` argument to determine which shortcut should be returned.

Returns

Type: ShortcutParams

# listDynamicShortcuts

Availability

5.1.0

listDynamicShortcuts() → Array<ShortcutParams>

Returns an array of the application shortcuts created dynamically.

Returns

Type: Array<ShortcutParams>

# listStaticShortcuts

Availability

5.1.0

listStaticShortcuts() → Array<ShortcutParams>

Returns an array of the application shortcuts listed in your tiapp.xml file.

Returns

Type: Array<ShortcutParams>

# removeAllDynamicShortcuts

Availability

5.1.0

removeAllDynamicShortcuts() → void

Removes all dynamically created application shortcuts.

Returns

Type: void

# removeDynamicShortcut

Availability

5.1.0

removeDynamicShortcut(identifier) → void

Removes the dynamic application shortcut item identified by the identifier.

Parameters

Name	Type	Description
`identifier`	String	Use the `identifier` argument to determine which shortcut should be removed.

Returns

Type: void

# removeEventListener

Availability

5.1.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