Protocol

UIText​Input

The protocol you implement to interact with the text input system and enable features such as autocorrection and multistage text input in documents.

Overview

Objects of classes that adopt the UIText​Input 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 UIText​Input 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 UIText​Input 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:

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

  • UIText​Input​Tokenizer protocol and UIText​Input​String​Tokenizer 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.

  • UIText​Input​Delegate 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.

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

The UIText​Input protocol also inherits the UIText​Input​Traits 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 UIText​Input protocol allow your app to respond to the completion of dictation, as described in Using Dictation. You can use an object of the UIDictation​Phrase 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.

Symbols

Replacing and Returning Text

func text(in:​ UIText​Range)

Return the text in the specified range.

func replace(UIText​Range, with​Text:​ String)

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

func should​Change​Text(in:​ UIText​Range, replacement​Text:​ String)

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

Working with Marked and Selected Text

var selected​Text​Range:​ UIText​Range?

The range of selected text in a document.

var marked​Text​Range:​ UIText​Range?

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

var marked​Text​Style:​ [Any​Hashable :​ Any]?

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

func set​Marked​Text(String?, selected​Range:​ NSRange)

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

func unmark​Text()

Unmark the currently marked text.

var selection​Affinity:​ UIText​Storage​Direction

The desired location for the insertion point.

Computing Text Ranges and Text Positions

func position(from:​ UIText​Position, offset:​ Int)

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

func position(from:​ UIText​Position, in:​ UIText​Layout​Direction, offset:​ Int)

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

var beginning​Of​Document:​ UIText​Position

The text position for the beginning of a document.

var end​Of​Document:​ UIText​Position

The text position for the end of a document.

Evaluating Text Positions

func compare(UIText​Position, to:​ UIText​Position)

Return how one text position compares to another text position.

func offset(from:​ UIText​Position, to:​ UIText​Position)

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

Determining Layout and Writing Direction

func position(within:​ UIText​Range, farthest​In:​ UIText​Layout​Direction)

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

func character​Range(by​Extending:​ UIText​Position, in:​ UIText​Layout​Direction)

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

func base​Writing​Direction(for:​ UIText​Position, in:​ UIText​Storage​Direction)

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

func set​Base​Writing​Direction(UIText​Writing​Direction, for:​ UIText​Range)

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

Geometry and Hit-Testing Methods

func first​Rect(for:​ UIText​Range)

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

func caret​Rect(for:​ UIText​Position)

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

func closest​Position(to:​ CGPoint)

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

func selection​Rects(for:​ UIText​Range)

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

func closest​Position(to:​ CGPoint, within:​ UIText​Range)

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

func character​Range(at:​ CGPoint)

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

Text Input Delegate and Text Input Tokenizer

var input​Delegate:​ UIText​Input​Delegate?

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

var tokenizer:​ UIText​Input​Tokenizer

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

Using Dictation

func dictation​Recording​Did​End()

Called when there is a pending dictation result.

func dictation​Recognition​Failed()

Called when dictation ended but recognition failed.

func insert​Dictation​Result([UIDictation​Phrase])

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

var insert​Dictation​Result​Placeholder:​ Any

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

func frame(for​Dictation​Result​Placeholder:​ Any)

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

func remove​Dictation​Result​Placeholder(Any, will​Insert​Result:​ Bool)

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

Returning Text Styling Information

func text​Styling(at:​ UIText​Position, in:​ UIText​Storage​Direction)

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:​ UIText​Range, at​Character​Offset:​ Int)

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

func character​Offset(of:​ UIText​Position, within:​ UIText​Range)

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

Returning the Text Input View

var text​Input​View:​ UIView

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

Constants

UIText​Storage​Direction

The direction of text storage.

UIText​Layout​Direction

The direction of text layout.

UIText​Writing​Direction

The writing direction of the text, based on language.

Style Dictionary Keys

A dictionary containing properties that define text style characteristics.

Relationships

Inherits From