iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UIInputViewController Class Reference

Options
Deployment Target:

On This Page
Language:

UIInputViewController

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 8.0 and later.

To create a custom keyboard, start by subclassing the UIInputViewController class. Add your keyboard’s user interface to the inputView property of your subclass.

Xcode 6 and later provides a starting point for a custom keyboard: the Custom Keyboard target template.

A custom keyboard can respond to user input events in the following ways:

  • Add text in the form of an unattributed NSString object at the insertion point in the current text input object, by calling the insertText: method on the textDocumentProxy property. This property provides that method through its conformance to the UIKeyInput protocol

  • Delete text in a backward direction, starting at the insertion point, by calling the deleteBackward method on the textDocumentProxy property.

  • Switch to another keyboard in the set of user-enabled keyboards, by calling the advanceToNextInputMode method.

  • Dismiss the keyboard, by calling the dismissKeyboard method.

Obtain textual context around the insertion point by reading the textDocumentProxy properties documentContextBeforeInput and documentContextAfterInput. To find out if the current text input object is empty, call the hasText method on the textDocumentProxy property. You can employ this textual context by considering it along with user input, to offer context-sensitive output to a document from your keyboard.

An input view controller conforms to the UITextInputDelegate protocol, allowing you to respond to changes in document content and position of the insertion point.

To present an appropriate keyboard layout, respond to the current text input object’s UIKeyboardType property. For each keyboard type trait you support, change the contents of your primary view accordingly.

For more about creating a custom keyboard, read Custom Keyboard in App Extension Programming Guide.

  • inputView inputView Property

    The primary view for the input view controller.

    Declaration

    Swift

    var inputView: UIInputView!

    Objective-C

    @property(nonatomic, retain) UIInputView *inputView

    Discussion

    When used as the primary view for an input view controller, a UIInputView object is empty. Add your keyboard’s user interface to this view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Switches to the next keyboard in the list of user-enabled keyboards.

    Declaration

    Swift

    func advanceToNextInputMode()

    Objective-C

    - (void)advanceToNextInputMode

    Discussion

    To pass app review, you must provide an obvious user interface control for the user to switch away from your keyboard.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Dismisses the custom keyboard from from the screen.

    Declaration

    Swift

    func dismissKeyboard()

    Objective-C

    - (void)dismissKeyboard

    Discussion

    Because a custom keyboard does not have access to the current text input object, you cannot send it a resignFirstResponder message (as you would to dismiss the system keyboard when you are developing an app with text entry). To dismiss the custom keyboard, call dismissKeyboard instead.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • A proxy to the text input object that the custom keyboard is interacting with. (read-only)

    Declaration

    Swift

    var textDocumentProxy: NSObject { get }

    Objective-C

    @property(nonatomic, readonly) NSObject < UITextDocumentProxy > *textDocumentProxy

    Discussion

    This property conforms directly or indirectly to the following protocols:

    • The UITextDocumentProxy protocol provides textual context around the insertion point

    • The UIKeyInput protocol provides the insert and delete methods, and lets you find out if the text object is empty

    • The UITextInputTraits protocol provides insight into the characteristics of the text input object, such as whether it requests a style of autocapitalization and which sort of keyboard it expects (for example, email address, URL, number pad, or default).

    Employ this property to interact with the current text input object. For example, to insert text you would write code like this:

    • [self.textDocumentProxy insertText:@"hello "]; // Inserts the string "hello " at the insertion point

    To delete code you’d write code like this:

    • [self.textDocumentProxy deleteBackward]; // Deletes the character to the left of the insertion point

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • Obtains a supplementary lexicon of term pairs for use in a custom keyboard.

    Declaration

    Swift

    func requestSupplementaryLexiconWithCompletion(_ completionHandler: (UILexicon!) -> Void)

    Objective-C

    - (void)requestSupplementaryLexiconWithCompletion:(void (^)(UILexicon *))completionHandler

    Parameters

    completionHandler

    Code that you write to make use of the returned UILexicon object.

    Discussion

    Call this method to obtain a UILexicon object containing a basic set of term pairs for use in autocorrection or textual suggestions based on user input. The UILexicon object contains words from various sources, including:

    • Unpaired first names and last names from the user’s Address Book database

    • Text shortcuts defined in the Settings > General > Keyboard > Shortcuts list

    • A common words dictionary

    Consider this lexicon as a supplement to a more complete lexicon of your own design.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.

  • The primary language for a custom keyboard.

    Declaration

    Swift

    var primaryLanguage: String?

    Objective-C

    @property(nonatomic, copy) NSString *primaryLanguage

    Discussion

    A BCP 47 language identifier, such as en-US. If specified, this value supersedes the PrimaryLanguage key in a custom keyboard’s Info.plist file.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 8.0 and later.