Skip to content
Titanium SDK

Version12.6.1

You are reading 12.6.1. See this page in 13.4.1.

Titanium.UI.iOS.ApplicationShortcuts

proxydeprecatediPhonesince 5.1.0

Extends Titanium.Proxy

Deprecated since 9.1.0

Use Titanium.UI.Shortcut instead.

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
ParametersTypeDescription
paramsShortcutParams

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
ParametersTypeDescription
nameString

Name of the event.

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

dynamicShortcutExists

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

Parameters
ParametersTypeDescription
identifierString

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
ParametersTypeDescription
nameString

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
ParametersTypeDescription
identifierString

Use the identifier argument to determine which shortcut should be returned.

Returns ShortcutParams

listDynamicShortcuts

Returns an array of the application shortcuts created dynamically.

Returns Array<ShortcutParams>

listStaticShortcuts

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

Returns Array<ShortcutParams>

removeDynamicShortcut

Removes the dynamic application shortcut item identified by the identifier.

Parameters
ParametersTypeDescription
identifierString

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
ParametersTypeDescription
nameString

Name of the event.

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