Protocol

UITextInput

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.

Declaration

@protocol UITextInput

Overview

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.

Topics

Replacing and Returning Text

- textInRange:

Return the text in the specified range.

Required.

- replaceRange:withText:

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

Required.

- shouldChangeTextInRange:replacementText:

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

Working with Marked and Selected Text

selectedTextRange

The range of selected text in a document.

Required.

markedTextRange

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

Required.

markedTextStyle

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

Required.

- setMarkedText:selectedRange:

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

Required.

- unmarkText

Unmark the currently marked text.

Required.

selectionAffinity

The desired location for the insertion point.

Computing Text Ranges and Text Positions

- textRangeFromPosition:toPosition:

Return the range between two text positions.

Required.

- positionFromPosition:offset:

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

Required.

- positionFromPosition:inDirection:offset:

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

Required.

beginningOfDocument

The text position for the beginning of a document.

Required.

endOfDocument

The text position for the end of a document.

Required.

Evaluating Text Positions

- comparePosition:toPosition:

Return how one text position compares to another text position.

Required.

- offsetFromPosition:toPosition:

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

Required.

Determining Layout and Writing Direction

- positionWithinRange:farthestInDirection:

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

Required.

- characterRangeByExtendingPosition:inDirection:

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

Required.

- baseWritingDirectionForPosition:inDirection:

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

Required.

- setBaseWritingDirection:forRange:

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

Required.

Geometry and Hit-Testing Methods

- firstRectForRange:

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

Required.

- caretRectForPosition:

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

Required.

- closestPositionToPoint:

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

Required.

- selectionRectsForRange:

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

Required.

- closestPositionToPoint:withinRange:

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

Required.

- characterRangeAtPoint:

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

Required.

Text Input Delegate and Text Input Tokenizer

inputDelegate

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

Required.

tokenizer

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

Required.

Managing the Floating Cursor

- beginFloatingCursorAtPoint:

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

- updateFloatingCursorAtPoint:

Called to move the floating cursor to a new location.

- endFloatingCursor

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

Using Dictation

- dictationRecordingDidEnd

Called when there is a pending dictation result.

- dictationRecognitionFailed

Called when dictation ended but recognition failed.

- insertDictationResult:

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

insertDictationResultPlaceholder

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

- frameForDictationResultPlaceholder:

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

- removeDictationResultPlaceholder:willInsertResult:

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

Returning Text Styling Information

- textStylingAtPosition:inDirection:

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

- positionWithinRange:atCharacterOffset:

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

- characterOffsetOfPosition:withinRange:

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

Returning the Text Input View

textInputView

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

Constants

UITextStorageDirection

The direction of text storage.

UITextLayoutDirection

The direction of text layout.

UITextDirection

A direction of the text.

UITextWritingDirection

The writing direction of the text, based on language.

Deprecated
Style Dictionary Keys

A dictionary containing properties that define text style characteristics.

Relationships

Inherits From

Conforming Types

See Also

Input

UITextInputDelegate

An intermediary between a document and the text input system.

UITextInputTokenizer

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

UIKeyInput

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

UITextInputMode

The current text-input mode.

UITextInputStringTokenizer

A base implementation of the UITextInputTokenizer protocol.

UIDictationPhrase

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

UIInputView

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