UITextInput Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 3.2 and later.
Companion guide
Declared in
UITextInput.h

Overview

Classes that adopt the UITextInput protocol (and conform with inherited protocols) interact with the text input system and thus acquire features such as autocorrection and multistage text input for their documents. (Multistage text input is required when the language is ideographic and the keyboard is phonetic.)

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 (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.

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:

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

Starting in iOS 5.1, 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.

Tasks

Replacing and Returning Text

Working with Marked and Selected Text

Computing Text Ranges and Text Positions

Evaluating Text Positions

Determining Layout and Writing Direction

Geometry and Hit-Testing Methods

Text Input Delegate and Text Input Tokenizer

Using Dictation

Returning Text Styling Information

Reconciling Text Position and Character Offset

Returning the Text Input View

Properties

beginningOfDocument

The text position for the beginning of a document. (required) (read-only)

@property(nonatomic, readonly) UITextPosition *beginningOfDocument
Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

endOfDocument

The text position for the end of a document. (required) (read-only)

@property(nonatomic, readonly) UITextPosition *endOfDocument
Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

inputDelegate

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

@property(nonatomic, assign) id<UITextInputDelegate> inputDelegate
Discussion

The text input system automatically assigns a delegate to this property at runtime. It is the responsibility of the view that adopts the UITextInput protocol to notify the input delegate at the appropriate junctures.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

markedTextRange

The range of text that is currently marked in a document. (required) (read-only)

@property(nonatomic, readonly) UITextRange *markedTextRange
Discussion

If there is no marked text, the value of the property is nil. Marked text is provisionally inserted text that requires user confirmation; it occurs in multistage text input. The current selection, which can be a caret or an extended range, always occurs within the marked text.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

markedTextStyle

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

@property(nonatomic, copy) NSDictionary *markedTextStyle
Discussion

Marked text requires a unique visual treatment when displayed to users. See “Style Dictionary Keys” for descriptions of the valid keys and values for this dictionary.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

selectedTextRange

The range of selected text in a document. (required)

@property(readwrite, copy) UITextRange *selectedTextRange
Discussion

If the text range has a length, it indicates the currently selected text. If it has zero length, it indicates the caret (insertion point). If the text-range object is nil, it indicates that there is no current selection.

Availability
  • Available in iOS 3.2 and later.
See Also
Declared In
UITextInput.h

selectionAffinity

The desired location for the insertion point.

@property(nonatomic) UITextStorageDirection selectionAffinity
Discussion

For text selections that wrap across line boundaries, this property determines whether the insertion point appears after the last character on the line or before the first character on the following line. The selection affinity is set in response to the user navigating via the keyboard (for example, command-right-arrow). The text input system checks this property when it moves the insertion point around in a document.

In the default implementation, if the selection is not at the end of the line, or if the selection is at the start of a paragraph for an empty line, a forward direction is assumed (UITextStorageDirectionForward); otherwise, a backward direction UITextStorageDirectionBackward is assumed.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

textInputView

An affiliated view that provides a coordinate system for all geometric values in this protocol. (read-only)

@property(nonatomic, readonly) UIView *textInputView
Discussion

The view that both draws the text and provides a coordinate system for all geometric values in this protocol. (This is typically an instance of the UITextInput-adopting class.) If this property is unimplemented, the first view in the responder chain is selected.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

tokenizer

An input tokenizer that provides information about the granularity of text units. (required) (read-only)

@property(nonatomic, readonly) id<UITextInputTokenizer> tokenizer
Discussion

Standard units of granularity include characters, words, lines, and paragraphs. In most cases, you may lazily create and assign an instance of a subclass of UITextInputStringTokenizer for this purpose. If you require different behavior than this system-provided tokenizer, you can create a custom tokenizer that adopts the UITextInputTokenizer protocol.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

Instance Methods

baseWritingDirectionForPosition:inDirection:

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

- (UITextWritingDirection)baseWritingDirectionForPosition:(UITextPosition *)position inDirection:(UITextStorageDirection)direction
Parameters
position

An object that identifies a location in a document.

direction

A constant that indicates a direction of storage (forward or backward).

Return Value

A constant that represents a writing direction (for example, left-to-right or right-to-left)

Discussion

The base writing direction is set previously when the text input system sends a setBaseWritingDirection:forRange: message to the conforming document object.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

caretRectForPosition:

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

- (CGRect)caretRectForPosition:(UITextPosition *)position
Parameters
position

An object that identifies a location in a document.

Return Value

A rectangle that defines the area for drawing the caret.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

characterOffsetOfPosition:withinRange:

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

- (NSInteger)characterOffsetOfPosition:(UITextPosition *)position withinRange:(UITextRange *)range
Parameters
position

An object that identifies a location in a document’s text.

range

An object that specifies a range of text in a document.

Return Value

The number of characters in a document's text that occur between position and the beginning of range.

Discussion

You should implement this method if you don’t have a one-to-one correspondence between UITextPosition objects within the given range and character offsets into a document string.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

characterRangeAtPoint:

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

- (UITextRange *)characterRangeAtPoint:(CGPoint)point
Parameters
point

A point in the view that is drawing a document’s text.

Return Value

An object representing a range that encloses a character (or characters) at point.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

characterRangeByExtendingPosition:inDirection:

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

- (UITextRange *)characterRangeByExtendingPosition:(UITextPosition *)position inDirection:(UITextLayoutDirection)direction
Parameters
position

A text-position object that identifies a location in a document.

direction

A constant that indicates a direction of layout (right, left, up, down).

Return Value

A text-range object that represents the distance from position to the farthest extent in direction.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

closestPositionToPoint:

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

- (UITextPosition *)closestPositionToPoint:(CGPoint)point
Parameters
point

A point in the view that is drawing a document’s text.

Return Value

An object locating a position in a document that is closest to point.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

closestPositionToPoint:withinRange:

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

- (UITextPosition *)closestPositionToPoint:(CGPoint)point withinRange:(UITextRange *)range
Parameters
point

A point in the view that is drawing a document’s text.

range

An object representing a range in a document’s text.

Return Value

An object representing the character position in range that is closest to point.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

comparePosition:toPosition:

Return how one text position compares to another text position. (required)

- (NSComparisonResult)comparePosition:(UITextPosition *)position toPosition:(UITextPosition *)other
Parameters
position

A custom object that represents a location within a document.

other

A custom object that represents another location within a document.

Return Value

A value that indicates whether the two text positions are identical or whether one is before the other.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

dictationRecognitionFailed

Called when dictation ended but recognition failed.

- (void)dictationRecognitionFailed
Discussion

Implement this optional method if you want to respond to failed dictation recognition.

Availability
  • Available in iOS 5.1 and later.
Declared In
UITextInput.h

dictationRecordingDidEnd

Called when there is a pending dictation result.

- (void)dictationRecordingDidEnd
Discussion

Implement this optional method if you want to respond to the completion of the recognition of a dictated phrase.

Availability
  • Available in iOS 5.1 and later.
Declared In
UITextInput.h

firstRectForRange:

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

- (CGRect)firstRectForRange:(UITextRange *)range
Parameters
range

An object that represents a range of text in a document.

Return Value

The first rectangle in a range of text. You might use this rectangle to draw a correction rectangle. The “first” in the name refers the rectangle enclosing the first line when the range encompasses multiple lines of text.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

frameForDictationResultPlaceholder:

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

- (CGRect)frameForDictationResultPlaceholder:(id)placeholder
Parameters
placeholder

A placeholder object provided by your app and used to identify the location of the dictation results.

Return Value

The rectangle, in the coordinate system of your input view, at which to display the dictation placeholder animation.

Discussion

While dictation results are being generated, UIKit displays the built-in dictation placeholder animation. Your implementation of this method should provide the rectangle at which to display this animation (at the location where the dictation results will be inserted).

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextInput.h

insertDictationResult:

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

- (void)insertDictationResult:(NSArray *)dictationResult
Parameters
dictationResult

An array of UIDictationPhrase objects.

Discussion

Implement this optional method if you want to support dictation phrase alternatives. If you do not implement this method, iOS inserts the most likely interpretation of the dictated phrase.

Availability
  • Available in iOS 5.1 and later.
Declared In
UITextInput.h

insertDictationResultPlaceholder

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

- (id)insertDictationResultPlaceholder
Return Value

A placeholder object to use to identify the dictation results. This value must not be nil.

Discussion

Implementation of this method is optional but can be done when you want to provide a specific rectangle for the placeholder animation while the dictation results are being processed. The object you return from this method is passed to the frameForDictationResultPlaceholder: method later. The actual contents of the object are not accessed by UIKit but you can use the object to store whatever information you need to identify the location for the animation.

UIKit maintains a strong reference to your placeholder object until the removeDictationResultPlaceholder:willInsertResult: method is called. You must implement both this method and the removeDictationResultPlaceholder:willInsertResult: method for placeholders to be used.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextInput.h

offsetFromPosition:toPosition:

Return the number of visible characters between one text position and another text position. (required)

- (NSInteger)offsetFromPosition:(UITextPosition *)fromPosition toPosition:(UITextPosition *)toPosition
Parameters
fromPosition

A custom object that represents a location within a document.

toPosition

A custom object that represents another location within document.

Return Value

The number of visible characters between fromPosition and toPosition.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

positionFromPosition:inDirection:offset:

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

- (UITextPosition *)positionFromPosition:(UITextPosition *)position inDirection:(UITextLayoutDirection)direction offset:(NSInteger)offset
Parameters
position

A custom UITextPosition object that represents a location in a document.

direction

A UITextLayoutDirection constant that represents the direction of the offset from position. Return nil if the computed text position is less than 0 or greater than the length of the backing string.

offset

A character offset from position.

Discussion

For an example of an implementation of the related method, positionFromPosition:offset:, see “Drawing and Managing Text”“ in Text Programming Guide for iOS.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

positionFromPosition:offset:

Returns the text position at a given offset from another text position. (required)

- (UITextPosition *)positionFromPosition:(UITextPosition *)position offset:(NSInteger)offset
Parameters
position

A custom UITextPosition object that represents a location in a document.

offset

A character offset from position. It can be a positive or negative value.

Return Value

A custom UITextPosition object that represents the location in a document that is at the specified offset from position. Return nil if the computed text position is less than 0 or greater than the length of the backing string.

Discussion

For an example of an implementation of this method, see “Drawing and Managing Text” in Text Programming Guide for iOS.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

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.

- (UITextPosition *)positionWithinRange:(UITextRange *)range atCharacterOffset:(NSInteger)offset
Parameters
range

An object that specifies a range of text in a document.

offset

A character offset from the start of range.

Return Value

An object that represents a position in a document’s visible text.

Discussion

You should implement this method if you don’t have a one-to-one correspondence between UITextPosition objects within the given range and character offsets into a document string.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

positionWithinRange:farthestInDirection:

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

- (UITextPosition *)positionWithinRange:(UITextRange *)range farthestInDirection:(UITextLayoutDirection)direction
Parameters
range

A text-range object that demarcates a range of text in a document.

direction

A constant that indicates a direction of layout (right, left, up, down).

Return Value

A text-position object that identifies a location in the visible text.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

removeDictationResultPlaceholder:willInsertResult:

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

- (void)removeDictationResultPlaceholder:(id)placeholder willInsertResult:(BOOL)willInsertResult
Parameters
placeholder

The placeholder object that is no longer needed.

willInsertResult

The value of this parameter is YES if the dictation value was generated successfully or NO if an error occurred.

Discussion

If the value in the willInsertResult parameter is NO, the placeholder animation is not replaced by an actual dictation result. When this happens, the system still removes the placeholder animation and removes the strong reference to your placeholder object.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextInput.h

replaceRange:withText:

Replace the text in a document that is in the specified range. (required)

- (void)replaceRange:(UITextRange *)range withText:(NSString *)text
Parameters
range

A range of text in a document.

text

A string to replace the text in range.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

selectionRectsForRange:

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

- (NSArray *)selectionRectsForRange:(UITextRange *)range
Parameters
range

An object representing a range in a document’s text.

Return Value

An array of UITextSelectionRect objects that encompass the selection.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextInput.h

setBaseWritingDirection:forRange:

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

- (void)setBaseWritingDirection:(UITextWritingDirection)writingDirection forRange:(UITextRange *)range
Parameters
writingDirection

A constant that represents a writing direction (for example, left-to-right or right-to-left)

range

An object that represents a range of text in a document.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

setMarkedText:selectedRange:

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

- (void)setMarkedText:(NSString *)markedText selectedRange:(NSRange)selectedRange
Parameters
markedText

The text to be marked.

selectedRange

A range within markedText that indicates the current selection. This range is always relative to markedText.

Discussion

Setting marked text either replaces the existing marked text or, if none is present, inserts it in place of the current selection.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

shouldChangeTextInRange:replacementText:

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

- (BOOL)shouldChangeTextInRange:(UITextRange *)range replacementText:(NSString *)text
Parameters
range

A range of text in a document.

text

The proposed text to replace the text in range.

Return Value

YES if the text should be changed or NO if it should not.

Discussion

Prior to replacing text, this method is called to give your delegate a chance to accept or reject the edits. If you do not implement this method, the return value defaults to YES.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextInput.h

textInRange:

Return the text in the specified range. (required)

- (NSString *)textInRange:(UITextRange *)range
Parameters
range

A range of text in a document.

Return Value

A substring of a document that falls within the specified range.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

textRangeFromPosition:toPosition:

Return the range between two text positions. (required)

- (UITextRange *)textRangeFromPosition:(UITextPosition *)fromPosition toPosition:(UITextPosition *)toPosition
Parameters
fromPosition

An object that represents a location in a document.

toPosition

An object that represents another location in a document.

Return Value

An object that represents the range between fromPosition and toPosition.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

textStylingAtPosition:inDirection:

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

- (NSDictionary *)textStylingAtPosition:(UITextPosition *)position inDirection:(UITextStorageDirection)direction
Parameters
position

An object that indicates a location in the text of a document.

direction

The direction of the styling attributes in text storage.

Return Value

A dictionary whose elements are one or more of the key-value pairs defining text color, font, and background color. See “Style Dictionary Keys” for descriptions of these key-value pairs.

Discussion

Text styling information can affect, for example, the appearance of a correction rectangle.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

unmarkText

Unmark the currently marked text. (required)

- (void)unmarkText
Discussion

After this method is called, the value of markedTextRange is nil.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

Constants

UITextStorageDirection

The direction of text storage.

typedef enum {
   UITextStorageDirectionForward = 0,
   UITextStorageDirectionBackward
} UITextStorageDirection;
Constants
UITextStorageDirectionForward

Storage of the text in a forward direction.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextStorageDirectionBackward

Storage of the text in a backward direction.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

Discussion

Constants of this type are used as arguments to the baseWritingDirectionForPosition:inDirection: and textStylingAtPosition:inDirection: methods.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

UITextLayoutDirection

The direction of text layout.

typedef enum {
   UITextLayoutDirectionRight = 2,
   UITextLayoutDirectionLeft,
   UITextLayoutDirectionUp,
   UITextLayoutDirectionDown
} UITextLayoutDirection;
Constants
UITextLayoutDirectionRight

Layout of the text to the right.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextLayoutDirectionLeft

Layout of the text to the left.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextLayoutDirectionUp

Layout of the text in an upward direction.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextLayoutDirectionDown

Layout of the text in a downward direction.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

UITextWritingDirection

The writing direction of the text, based on language.

typedef enum {
   UITextWritingDirectionNatural = -1,
   UITextWritingDirectionLeftToRight = 0,
   UITextWritingDirectionRightToLeft,
} UITextWritingDirection;
Constants
UITextWritingDirectionNatural

The natural writing direction as defined by the Bidi algorithm.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextWritingDirectionLeftToRight

Writing that goes from left to right.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextWritingDirectionRightToLeft

Writing that goes from right to left.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

Discussion

Constants of this type are returned from the baseWritingDirectionForPosition:inDirection: method and are used as arguments of the setBaseWritingDirection:forRange: method.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextInput.h

Style Dictionary Keys

A dictionary containing properties that define text style characteristics.

NSString *const UITextInputTextBackgroundColorKey;
NSString *const UITextInputTextColorKey;
NSString *const UITextInputTextFontKey;
Constants
UITextInputTextBackgroundColorKey

The background color of the text. The value of this key is a UIColor object.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextInputTextColorKey

The color of the text. The value of this key is a UIColor object.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

UITextInputTextFontKey

The font of the text. The value of this key is a UIFont object.

Available in iOS 3.2 and later.

Declared in UITextInput.h.

Discussion

The style NSDictionary object is used for providing styling information for marked text (markedTextStyle property) and for providing text-styling information at a certain position (textStylingAtPosition:inDirection: method).