A set of methods you implement to interact with the text input system and enable features such as autocorrection and multistage text input in documents.


protocol UITextInput


Objects of classes that adopt the UITextInput protocol provide the text input system with text positions and text ranges on demand, answer questions about layout and writing direction, perform hit-testing—that is, returning text positions and ranges for a given point—and provide the system with rectangles that can be used for highlighting ranges of text and drawing the caret. In addition, a UITextInput object maintains ranges for selected text and marked text.

Marked text, which is part of multistage text input, represents provisionally inserted text that the user has yet to confirm. It is styled in a distinctive way. The range of marked text always contains within it a range of selected text, which might be a range of characters or the caret.

(Multistage text input is required when the language is ideographic and the keyboard is phonetic.)

The UITextInput protocol is the center of a constellation of classes and protocols for integrating text-processing applications with the text input system. The other parts of this constellation are the following:

  • UITextPosition and UITextRange classes—All UITextInput-conforming document classes must create custom subclasses of these classes. A UITextPosition object represents a position in a text container. A UITextRange object, which encapsulates beginning and ending UITextPosition objects, represents a range of characters in the text container.

  • UITextInputTokenizer protocol and UITextInputStringTokenizer class—The protocol defines an interface for a tokenizer object that enables the text input system to evaluate text units of different granularities. The class is a default implementation of this protocol.

  • UITextInputDelegate protocol—The text input system automatically assigns its own text input delegate (which conforms to this protocol) to the UITextInput-conforming document object. Through this text input delegate, a document object informs the text input system of changes in text and selection.

  • UIKeyInput protocol—Implemented to acquire the capabilities of text entry and deletion at an insertion point.

The UITextInput protocol also inherits the UITextInputTraits protocol, and thus the ability to customize the keyboard and its behaviors.

When the user chooses dictation input on a supported device, the system automatically inserts recognized phrases into the current text view. Methods in the UITextInput protocol allow your app to respond to the completion of dictation, as described in Using Dictation. You can use an object of the UIDictationPhrase class to obtain a string representing a phrase a user has dictated. In the case of ambiguous dictation results, a dictation phrase object provides an array containing alternative strings.


Replacing and Returning Text

func text(in: UITextRange) -> String?

Return the text in the specified range.


func replace(UITextRange, withText: String)

Replace the text in a document that is in the specified range.


func shouldChangeText(in: UITextRange, replacementText: String) -> Bool

Asks whether the text in the specified range should be replaced.

Working with Marked and Selected Text

var selectedTextRange: UITextRange?

The range of selected text in a document.


var markedTextRange: UITextRange?

The range of text that is currently marked in a document.


var markedTextStyle: [NSAttributedString.Key : Any]?

A dictionary of attributes that describes how marked text should be drawn.


func setMarkedText(String?, selectedRange: NSRange)

Insert the provided text and marks it to indicate that it is part of an active input session.


func unmarkText()

Unmark the currently marked text.


var selectionAffinity: UITextStorageDirection

The desired location for the insertion point.

Computing Text Ranges and Text Positions

func textRange(from: UITextPosition, to: UITextPosition) -> UITextRange?

Return the range between two text positions.


func position(from: UITextPosition, offset: Int) -> UITextPosition?

Returns the text position at a given offset from another text position.


func position(from: UITextPosition, in: UITextLayoutDirection, offset: Int) -> UITextPosition?

Returns the text position at a given offset in a specified direction from another text position.


var beginningOfDocument: UITextPosition

The text position for the beginning of a document.


var endOfDocument: UITextPosition

The text position for the end of a document.


Evaluating Text Positions

func compare(UITextPosition, to: UITextPosition) -> ComparisonResult

Return how one text position compares to another text position.


func offset(from: UITextPosition, to: UITextPosition) -> Int

Return the number of UTF-16 characters between one text position and another text position.


Determining Layout and Writing Direction

func position(within: UITextRange, farthestIn: UITextLayoutDirection) -> UITextPosition?

Return the text position that is at the farthest extent in a given layout direction within a range of text.


func characterRange(byExtending: UITextPosition, in: UITextLayoutDirection) -> UITextRange?

Return a text range from a given text position to its farthest extent in a certain direction of layout.


func baseWritingDirection(for: UITextPosition, in: UITextStorageDirection) -> NSWritingDirection

Return the base writing direction for a position in the text going in a certain direction.


func setBaseWritingDirection(NSWritingDirection, for: UITextRange)

Set the base writing direction for a given range of text in a document.


Geometry and Hit-Testing Methods

func firstRect(for: UITextRange) -> CGRect

Return the first rectangle that encloses a range of text in a document.


func caretRect(for: UITextPosition) -> CGRect

Return a rectangle used to draw the caret at a given insertion point.


func closestPosition(to: CGPoint) -> UITextPosition?

Return the position in a document that is closest to a specified point.


func selectionRects(for: UITextRange) -> [UITextSelectionRect]

Returns an array of selection rects corresponding to the range of text.


func closestPosition(to: CGPoint, within: UITextRange) -> UITextPosition?

Return the position in a document that is closest to a specified point in a given range.


func characterRange(at: CGPoint) -> UITextRange?

Return the character or range of characters that is at a given point in a document.


Text Input Delegate and Text Input Tokenizer

var inputDelegate: UITextInputDelegate?

An input delegate that is notified when text changes or when the selection changes.


var tokenizer: UITextInputTokenizer

An input tokenizer that provides information about the granularity of text units.


Managing the Floating Cursor

func beginFloatingCursor(at: CGPoint)

Called at the beginning of the gesture that the system uses to manipulate the cursor.

func updateFloatingCursor(at: CGPoint)

Called to move the floating cursor to a new location.

func endFloatingCursor()

Called at the end of the gesture that the system uses to manipulate the cursor

Using Dictation

func dictationRecordingDidEnd()

Called when there is a pending dictation result.

func dictationRecognitionFailed()

Called when dictation ended but recognition failed.

func insertDictationResult([UIDictationPhrase])

Called when there is more than one interpretation of a spoken phrase in a dictation result.

var insertDictationResultPlaceholder: Any

Asks for the placeholder object to use while dictation results are being generated.

func frame(forDictationResultPlaceholder: Any) -> CGRect

Asks for the rectangle in which to display the dictation placeholder animation.

func removeDictationResultPlaceholder(Any, willInsertResult: Bool)

Tells the view that the specified placeholder object is no longer needed.

Returning Text Styling Information

func textStyling(at: UITextPosition, in: UITextStorageDirection) -> [NSAttributedString.Key : Any]?

Return a dictionary with properties that specify how text is to be style at a certain location in a document.

Reconciling Text Position and Character Offset

func position(within: UITextRange, atCharacterOffset: Int) -> UITextPosition?

Return the position within a range of a document’s text that corresponds to the character offset from the start of that range.

func characterOffset(of: UITextPosition, within: UITextRange) -> Int

Return the character offset of a position in a document’s text that falls within a given range.

Returning the Text Input View

var textInputView: UIView

An affiliated view that provides a coordinate system for all geometric values in this protocol.


enum UITextStorageDirection

The direction of text storage.

enum UITextLayoutDirection

The direction of text layout.

struct UITextDirection

A direction of the text.

typealias UITextWritingDirection

The writing direction of the text, based on language.

Style Dictionary Keys

A dictionary containing properties that define text style characteristics.


Inherits From

Conforming Types

See Also


protocol UITextInputDelegate

An intermediary between a document and the text input system.

protocol UITextInputTokenizer

A tokenizer, which is an object that allows the text input system to evaluate text units of different granularities.

protocol UIKeyInput

A set of methods a subclass of UIResponder uses to implement simple text entry.

class UITextInputMode

The current text-input mode.

class UITextInputStringTokenizer

A base implementation of the UITextInputTokenizer protocol.

class UIDictationPhrase

An object that represents the textual interpretation of a spoken phrase as dictated by a user.

class UIInputView

An object that displays and manages custom input for a view when that view becomes the first responder.