Titanium Mobile

# Titanium.UI.ShortcutItem

An application shortcut item.

Availability
7.5.0
9.1.0
9.2.0
Extends
Titanium.Proxy

# Overview

Allows the creation of dynamic application shortcut items which can be set in the app to offer a dynamic behavior at runtime.

Use the Titanium.UI.createShortcutItem method to create a shortcut item and pass it to the Titanium.UI.Shortcut.add method to add it to the application.

# Android Static Shortcuts

Google documents how to add static shortcuts here (opens new window).

In the tiapp.xml file, you will need to add a shortcuts <meta-data/> element to your main activity.

<ti:app>
    <android>
        <manifest>
            <application>
                <activity android:name=".<Yourapplicationname>Activity">
                    <intent-filter>
                        <action android:name="android.intent.action.MAIN"/>
                        <category android:name="android.intent.category.LAUNCHER"/>
                    </intent-filter>
                    <meta-data android:name="android.app.shortcuts" android:resource="@xml/shortcuts"/>
                </activity>
            </application>
        </manifest>
    </android>
</ti:app>

You will also need to create a shortcuts.xml file as shown below, defining all of the app's static shortcuts. This file must reside in the Titanium project's ./platform/android/res/xml folder. Note that XML attributes icon, shortcutShortLabel, shortcutLongLabel, and shortcutDisabledMessage must be defined as string resources under the project's i18n folders or ./platform/android/res/values folders. Attributes targetPackage and targetClass need to be set to your project id and app name.

<shortcuts xmlns:android="http://schemas.android.com/apk/res/android">
  <shortcut
    android:shortcutId="my_unique_string_id"
    android:enabled="true"
    android:icon="@drawable/my_shortcut_icon"
    android:shortcutShortLabel="@string/my_shortcut_short_label"
    android:shortcutLongLabel="@string/my_shortcut_long_label"
    android:shortcutDisabledMessage="@string/my_shortcut_disabled_message">
    <intent
      android:action="android.intent.action.VIEW"
      android:targetPackage="<id_from_tiapp_xml>"
      android:targetClass="<id_from_tiapp_xml>.<Yourapplicationname>Activity" />
    <categories android:name="android.shortcut.conversation" />
  </shortcut>
  <!-- Add more shortcuts here. -->
</shortcuts>

# iOS Static Shortcuts

Static shortcut items can be set in the <ios> section of the tiapp.xml before launching the app.

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 (opens new window).

# Properties

# data CREATION ONLY

Availability
7.5.0
9.1.0
9.2.0
data :Object

Shortcut data.

Additional data that can be stored with the shortcut.

# description CREATION ONLY

Availability
7.5.0
9.1.0
9.2.0
description :String

Description of the shortcut.

In iOS the description can be localized. See here for more infos.

# icon CREATION ONLY

Availability
7.5.0
9.1.0
9.2.0
icon :String | Number

Shortcut icon.

This can be set as a resource id or file path.

In iOS, you can use constants Titanium.UI.iOS.SHORTCUT_ICON_TYPE_* or a reference to a Titanium.Contacts.Person as well. On iOS 13 and higher, you can pass in the Ti.Blob instance returned from <Ti.UI.iOS.systemImage> also.

In iOS, if you are using an image file, enable slicing (adding the image to an asset catalog) for the project. To enable slicing, add the use-app-thinning element to the ios element in the tiapp.xml file and set the value to true. If you do not enable slicing, the image will not be displayed.

<ti:app>
    <ios>
    <use-app-thinning>true</use-app-thinning>
    </ios>
</ti:app>

The recommended size for image files is 35dp (@2px: 70dp, @3x: 105dp). Also check the Apple documentation
for more information on shortcut icons.

# id CREATION ONLY

Availability
7.5.0
9.1.0
9.2.0
id :String

Determines shortcut id.

This should be a unique identifier for the shortcut.

# title CREATION ONLY

Availability
7.5.0
9.1.0
9.2.0
title :String

Title of the shortcut.

In iOS the title can be localized. See here for more infos.

# visible DEPRECATED

Availability
7.5.0
visible :Boolean

DEPRECATED SINCE 9.1.0

Use items to determine if shortcut is active.

Shortcut visibility.

Determines if the shortcut is visible.

# Methods

# hide DEPRECATED

Availability
7.5.0
hide() → void

DEPRECATED SINCE 9.1.0

Use remove instead.

Hide the shortcut.

Returns

Type
void

# pin

Availability
7.5.0
pin() → void

Pin shortcut to launcher.

Returns

Type
void

# show DEPRECATED

Availability
7.5.0
show() → void

DEPRECATED SINCE 9.1.0

Use add instead.

Allow the shortcut to show.

Returns

Type
void

Contents