# Titanium.UI.ShortcutItem

> An application shortcut item.

- Source: https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.UI.ShortcutItem
- Titanium SDK version: 13.1.1
- Kind: proxy
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 7.5.0, iPhone 9.1.0, iPad 9.1.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createShortcutItem) method to create a shortcut item and pass it to
the [Titanium.UI.Shortcut.add](https://titaniumsdk.com/docs/sdk/Titanium.UI.Shortcut.md#add) method to add it to the application.

#### Android Static Shortcuts
Google documents how to add static shortcuts
[here](https://developer.android.com/guide/topics/ui/shortcuts/creating-shortcuts#static).

In the `tiapp.xml` file, you will need to add a shortcuts `<meta-data/>` element to your main activity.
``` xml
<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.
``` xml
<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`:
``` 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.

## Properties

### data

- Type: Object
- Platforms: Android, iPhone, iPad, macOS

Shortcut data.

Additional data that can be stored with the shortcut.

### description

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Description of the shortcut.

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

### icon

- Type: String | Number
- Platforms: Android, iPhone, iPad, macOS

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](https://titaniumsdk.com/docs/sdk/Titanium.Contacts.Person.md) as well. On iOS 13 and higher, you can pass in the Ti.Blob instance returned from [Ti.UI.iOS.systemImage](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#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.

``` xml
<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](https://developer.apple.com/documentation/uikit/uiapplicationshortcuticon)  
for more information on shortcut icons.

### id

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Determines shortcut id.

This should be a unique identifier for the shortcut.

### title

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Title of the shortcut.

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

### visible

- Type: Boolean
- Platforms: Android
- DEPRECATED since 9.1.0. Use [Titanium.UI.Shortcut.items](Titanium.UI.Shortcut.items) to determine if shortcut is active.

Shortcut visibility.

Determines if the shortcut is visible.

## Methods

### hide

- Platforms: Android
- DEPRECATED since 9.1.0. Use [Titanium.UI.Shortcut.remove](Titanium.UI.Shortcut.remove) instead.

Hide the shortcut.

### pin

- Platforms: Android
- Requires: Android 8.0+

Pin shortcut to launcher.

### show

- Platforms: Android
- DEPRECATED since 9.1.0. Use [Titanium.UI.Shortcut.add](Titanium.UI.Shortcut.add) instead.

Allow the shortcut to show.

## Inherited members

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

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `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`.