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

- Source: https://titaniumsdk.com/docs/sdk/13.3.0/Titanium.UI.iOS.ApplicationShortcuts
- Titanium SDK version: 13.3.0
- Kind: proxy
- Platforms: iPhone
- Since: Titanium SDK 5.1.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy
- DEPRECATED since 9.1.0. Use [Titanium.UI.Shortcut](Titanium.UI.Shortcut) instead.

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](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.md) 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`:
``` xml
<ti:app>
    <!-- ... -->
    <ios>
        <plist>  
            <dict>
            <key>UIApplicationShortcutItems</key>
            <array>
                <dict>
                    <key>UIApplicationShortcutItemIconType</key>
                    [string](https://titaniumsdk.com/docs/sdk/Global.String.md)UIApplicationShortcutIconTypeSearch</string>
                    <key>UIApplicationShortcutItemTitle</key>
                    [string](https://titaniumsdk.com/docs/sdk/Global.String.md)My title</string>
                    <key>UIApplicationShortcutItemSubtitle</key>
                    [string](https://titaniumsdk.com/docs/sdk/Global.String.md)My subtitle</string>
                    <key>UIApplicationShortcutItemType</key>
                    [string](https://titaniumsdk.com/docs/sdk/Global.String.md)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](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#forceTouchSupported) property.
You cannot test 3D touch on the iOS simulator.

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

``` js
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();
```

## Example: Add a Titanium.Contact.Person as icon.

``` js
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();
```

## Methods

### addDynamicShortcut

- Platforms: iPhone

Creates a new dynamic application shortcut item.

Parameters:

- `params` (ShortcutParams): The parameters used when creating a dynamic shortcut.

### dynamicShortcutExists

- Platforms: iPhone

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

Parameters:

- `identifier` (String): Checks if the dynamic application shortcut item identified by the `identifier` exists.

Returns: Boolean

### getDynamicShortcut

- Platforms: iPhone

Gets the dynamic application shortcut item identified by the `identifier`.

Parameters:

- `identifier` (String): Use the `identifier` argument to determine which shortcut should be returned.

Returns: ShortcutParams

### listDynamicShortcuts

- Platforms: iPhone

Returns an array of the application shortcuts created dynamically.

Returns: Array<ShortcutParams>

### listStaticShortcuts

- Platforms: iPhone

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

Returns: Array<ShortcutParams>

### removeAllDynamicShortcuts

- Platforms: iPhone

Removes all dynamically created application shortcuts.

### removeDynamicShortcut

- Platforms: iPhone

Removes the dynamic application shortcut item identified by the `identifier`.

Parameters:

- `identifier` (String): Use the `identifier` argument to determine which shortcut should be removed.

## Inherited members

6 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.3.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.