Titanium.UI.iOS.ApplicationShortcuts

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

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

Properties #

apiName#

extended

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

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

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.

Methods #

addDynamicShortcut #

Creates a new dynamic application shortcut item.

Parameters:

Name	Type	Summary	Optional
`params`	`ShortcutParams`	The parameters used when creating a dynamic shortcut.	No

addEventListener #

extended

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

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

dynamicShortcutExists #

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

Parameters:

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

Returns: Boolean

fireEvent #

extended

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

getDynamicShortcut #

Gets the dynamic application shortcut item identified by the identifier.

Parameters:

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

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>

removeAllDynamicShortcuts #

Removes all dynamically created application shortcuts.

removeDynamicShortcut #

Removes the dynamic application shortcut item identified by the identifier.

Parameters:

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

removeEventListener #

extended

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

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

Notificationchannels

Launchoptionstype

Notificationparams

Usernotificationattachment

Usernotificationsettings

Mediascannerresponse

Clipboarditemstype

Systemimageparameters

Titanium.UI.iOS.ApplicationShortcuts ​

Properties #

apiName#

bubbleParent#

lifecycleContainer#

Methods #

addDynamicShortcut #

addEventListener #

applyProperties #

dynamicShortcutExists #

fireEvent #

getDynamicShortcut #

listDynamicShortcuts #

listStaticShortcuts #

removeAllDynamicShortcuts #

removeDynamicShortcut #

removeEventListener #

Examples #

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

Add a Titanium.Contact.Person as icon.

Titanium.UI.iOS.ApplicationShortcuts