Class

UIApplicationShortcutItem

An application shortcut item, also called a Home screen dynamic quick action, that specifies a user-initiated action for your app.

Overview

On a device that supports 3D Touch, a user invokes the quick action by pressing your app's icon on the Home screen and then selecting the quick action’s title. Your app delegate receives and handles the quick action.

You must specify the characteristics of your UIApplicationShortcutItem instances during initialization, before you register them with your app object. The quick actions you’ve registered with your app object are immutable.

Registering an Array of Dynamic Quick Actions With Your App

To register an array of Home screen dynamic quick actions, set the value of your shared app object’s shortcutItems property with an NSArray instance containing your defined dynamic Home screen quick actions.

Changing Your App’s Dynamic Quick Actions

To change your app’s Home screen dynamic quick actions, replace your app object’s shortcutItems array by setting a new value for the property. As a convenience for working with registered quick actions, this class has a mutable subclass, UIMutableApplicationShortcutItem. The following code snippet illustrates one way to use the mutableCopy() method, along with mutable quick actions, to change the title of a dynamic Home screen quick action:

let existingShortcutItems = UIApplication.sharedApplication().shortcutItems ?? []
let anExistingShortcutItem = existingShortcutItems[anIndex]
var updatedShortcutItems = existingShortcutItems
let aMutableShortcutItem = anExistingShortcutItem.mutableCopy() as! UIMutableApplicationShortcutItem
aMutableShortcutItem.localizedTitle = “New Title"
updatedShortcutItems[anIndex] = aMutableShortcutItem
UIApplication.sharedApplication().shortcutItems = updatedShortcutItems

Dynamic vs. Static Quick Actions

Although immutable, a UIApplicationShortcutItem instance is considered dynamic to distinguish it from a static quick action you specify at build time.

  • Define Home screen dynamic quick actions using this class. Your code creates dynamic quick actions, and registers them with your app object, at runtime.

  • Define Home screen static quick actions in the UIApplicationShortcutItems array in your Xcode project’s Info.plist file, as described in the iOS Keys chapter in Information Property List Key Reference. The system registers your static quick actions when your app is installed.

The system limits the number quick actions displayed when a user presses a Home screen app icon. Within the limited set of displayed quick action titles, your static quick actions are shown first, starting at the topmost position in the list. If your static items do not consume the permissible number for display and you have also defined dynamic quick actions using this class, then one or more of your dynamic quick actions is displayed.

App Launch and App Update Considerations for Quick Actions

When a user chooses one of your Home screen quick actions, the system launches or resumes your app and UIKit calls the application(_:performActionFor:completionHandler:) method in your app delegate. Be sure to read the description of that method in UIApplicationDelegate for information on how to ensure the method is called only when it should be.

After a user first installs your app and before they first launch it, pressing your Home screen icon displays only the app’s static quick actions. After first launch, your dynamic quick actions (if you’ve defined any and there is room in the list to accommodate them) are displayed as well.

If a user installs an update for your app but has not yet launched the update, pressing your Home screen icon shows the dynamic quick actions for the previously-installed version. One way to gracefully handle this scenario is to provide app version information in the userInfo dictionary of a quick action.

Topics

Creating a Home Screen Dynamic Quick Action

init(type: String, localizedTitle: String)

Creates an immutable Home screen dynamic quick action with a user-visible title and no icon.

init(type: String, localizedTitle: String, localizedSubtitle: String?, icon: UIApplicationShortcutIcon?, userInfo: [AnyHashable : Any]? = nil)

Creates an immutable Home screen dynamic quick action with user-visible title, icon, and userInfo dictionary.

Inspecting a Home Screen Dynamic Quick Action

var localizedTitle: String

The required, user-visible title for the Home screen dynamic quick action.

var localizedSubtitle: String?

The optional, user-visible subtitle for the Home screen dynamic quick action.

var type: String

A required, app-specific string that you employ to identify the type of quick action to perform.

var icon: UIApplicationShortcutIcon?

The optional icon for the Home screen dynamic quick action.

var userInfo: [String : NSSecureCoding]?

Optional, app-specific information that you can provide for use when your app performs the Home screen quick action.

See Also

Home Screen

class UIApplicationShortcutIcon

An image you can optionally associate with a Home screen quick action to improve its appearance and usability.

class UIMutableApplicationShortcutItem

An item that specifies a configurable user-initiated action for your app (the item is also called a mutable Home screen dynamic quick action).