Version13.0.1

You are reading 13.0.1. See this page in 13.4.1.

Titanium.UI.iOS.ApplicationShortcuts

proxydeprecatediPhonesince 5.1.0

Deprecated since 9.1.0

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.

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](api:Global.String)UIApplicationShortcutIconTypeSearch</string>
                    <key>UIApplicationShortcutItemTitle</key>
                    [string](api:Global.String)My title</string>
                    <key>UIApplicationShortcutItemSubtitle</key>
                    [string](api:Global.String)My subtitle</string>
                    <key>UIApplicationShortcutItemType</key>
                    [string](api:Global.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 2

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

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

Default: true

Methods 11

addDynamicShortcut

Creates a new dynamic application shortcut item.

Parameters
Parameters	Type	Description
params	ShortcutParams	The parameters used when creating a dynamic shortcut. 5 fields icon? Number \| String \| Titanium.Contacts.Person The icon to be displayed on the application shortcut. You can either use one of the constants like Titanium.UI.iOS.SHORTCUT_ICON_TYPE_COMPOSE, a local image specified by the image path or a reference to a Titanium.Contacts.Person. identifier String The unique key for the application shortcut. Equates to the underlying `UIApplicationShortcutItemIconType` key subtitle? String The subtitle displayed on the application shortcut. title String The title of the application shortcut. userInfo? Object The userInfo of the application shortcut.

addEventListener

Inherited from Titanium.Proxy

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

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

applyProperties

since 3.0.0

Inherited from Titanium.Proxy

Applies the properties to the proxy.

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

dynamicShortcutExists

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

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

Returns Boolean

fireEvent

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

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

getDynamicShortcut

Gets the dynamic application shortcut item identified by the identifier.

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

Returns ShortcutParams

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

removeEventListener

Inherited from Titanium.Proxy

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

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.