Class

UITextInputAssistantItem

An object that manages bar button items displayed in the shortcuts bar above the keyboard on iPad.

Overview

Use a UITextInputAssistantItem object to add app-specific actions to the shortcuts bar. The center of the shortcuts bar displays typing suggestions for the user. You can install custom bar button items that lead or trail the typing suggestions.

You do not create instances of this class directly. Instead, you get an input assistant from the inputAssistantItem property of the responder object whose keyboard you want to modify. When the keyboard is displayed, UIKit automatically searches the responder chain for a text input assistant object. Typically, you assign the text input assistant to the object that becomes the first responder, but you may also assign it to a parent responder object in order to share a set of shortcuts among multiple children.

The bar button items you create for the shortcuts bar must be organized into groups. A UIBarButtonItemGroup object manages each group of items, and each group may contain a single item or several items. UIKit displays as many items as possible based on the available space. When there is not enough space for all of the items, UIKit collapses each group of items down to a single representative item to make more space.

Listing 1 shows a code snippet for configuring the items of the shortcuts bar. After creating the bar button items, this code creates a group and assigns that group to the leadingBarButtonGroups property. The resulting items are displayed before the typing suggestions.

Listing 1

Configuring a text input assistant item

// Get a UITextView object of the current view controller.
UITextInputAssistantItem* item = [self.textView inputAssistantItem];
 
UIBarButtonItem* itemOne = [[UIBarButtonItem alloc] initWithTitle:@"One"
         style:UIBarButtonItemStylePlain target:self action:@selector(handleItemOne:)];
UIBarButtonItem* itemTwo = [[UIBarButtonItem alloc] initWithTitle:@"Two"
         style:UIBarButtonItemStylePlain target:self action:@selector(handleItemTwo:)];
UIBarButtonItem* itemThree = [[UIBarButtonItem alloc] initWithTitle:@"Three"
         style:UIBarButtonItemStylePlain target:self action:@selector(handleItemThree:)];
 
// Use a nil action to display the individual items when tapped.
UIBarButtonItem* itemChoose = [[UIBarButtonItem alloc] initWithTitle:@"Choose"
         style:UIBarButtonItemStylePlain target:nil action:nil];
 
// Create the item group.
UIBarButtonItemGroup* group = [[UIBarButtonItemGroup alloc]
       initWithBarButtonItems:@[itemOne, itemTwo, itemThree] representativeItem:itemChoose];
 
// Display the items before the typing suggestions.
item.leadingBarButtonGroups = @[group];

To hide shortcuts altogether, set the leadingBarButtonGroups and trailingBarButtonGroups properties to nil. Doing so hides only the shortcuts and does not hide the typing suggestions. To hide typing suggestions, you must also set the autocorrectionType property of the responder that displays the keyboard to no.

Topics

Configuring the Shortcut Bar

var leadingBarButtonGroups: [UIBarButtonItemGroup]

The array of button item groups to display before the typing suggestions.

var trailingBarButtonGroups: [UIBarButtonItemGroup]

The array of button item groups to display after the typing suggestions.

var allowsHidingShortcuts: Bool

A Boolean value indicating whether the shortcuts bar may be hidden by the user.

Relationships

Inherits From

Conforms To

See Also

Configuration

protocol UITextInputTraits

A collection of methods that defines features associated with keyboard input to a text object.