Protocol: UITextInput

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.) The text position for the beginning of a document. (required) (read-only)The text position for the end of a document. (required) (read-only)An input delegate that is notified when text changes or when the selection changes. (required)The range of text that is currently marked in a document. (required) (read-only)A dictionary of attributes that describes how marked text should be drawn. (required)The range of selected text in a document. (required)The desired location for the insertion point.An affiliated view that provides a coordinate system for all geometric values in this protocol. (read-only)An input tokenizer that provides information about the granularity of text units. (required) (read-only)Return the base writing direction for a position in the text going in a certain direction. (required)Return a rectangle used to draw the caret at a given insertion point. (required)Return the character offset of a position in a document’s text that falls within a given range.Return the character or range of characters that is at a given point in a document. (required)Return a text range from a given text position to its farthest extent in a certain direction of layout. (required)Return the position in a document that is closest to a specified point. (required)Return the position in a document that is closest to a specified point in a given range. (required)Return how one text position compares to another text position. (required)Called when dictation ended but recognition failed.Called when there is a pending dictation result.Return the first rectangle that encloses a range of text in a document. (required)Asks for the rectangle in which to display the dictation placeholder animation.Called when there is more than one interpretation of a spoken phrase in a dictation result.Asks for the placeholder object to use while dictation results are being generated. Return the number of visible characters between one text position and another text position. (required)Returns the text position at a given offset in a specified direction from another text position. (required)Returns the text position at a given offset from another text position. (required)Return the position within a range of a document’s text that corresponds to the character offset from the start of that range.Return the text position that is at the farthest extent in a given layout direction within a range of text.Tells the view that the specified placeholder object is no longer needed.Replace the text in a document that is in the specified range. (required)Returns an array of selection rects corresponding to the range of text. (required)Set the base writing direction for a given range of text in a document. (required)Insert the provided text and marks it to indicate that it is part of an active input session. (required)Asks whether the text in the specified range should be replaced. Return the text in the specified range. (required)Return the range between two text positions. (required)Return a dictionary with properties that specify how text is to be style at a certain location in a document.Unmark the currently marked text. (required)The direction of text storage.The direction of text layout.The writing direction of the text, based on language.A dictionary containing properties that define text style characteristics.

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Instance Attribute Details

- (UITextPosition) beginningOfDocument (readonly)

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

Returns:

- (UITextPosition) endOfDocument (readonly)

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

Returns:

- (Object) inputDelegate

An input delegate that is notified when text changes or when the selection changes. (required) 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.

Returns:

- (UITextRange) markedTextRange (readonly)

The range of text that is currently marked in a document. (required) (read-only) 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.

Returns:

- (Hash) markedTextStyle

A dictionary of attributes that describes how marked text should be drawn. (required) 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.

Returns:

- (UITextRange) selectedTextRange

The range of selected text in a document. (required) 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.

Returns:

- (UITextStorageDirection) selectionAffinity

The desired location for the insertion point. 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.

Returns:

- (UIView) textInputView (readonly)

An affiliated view that provides a coordinate system for all geometric values in this protocol. (read-only) 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.

Returns:

- (Object) tokenizer (readonly)

An input tokenizer that provides information about the granularity of text units. (required) (read-only) 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.

Returns:

Instance Method Details

- (UITextWritingDirection) baseWritingDirectionForPosition(position, inDirection:direction)

Return the base writing direction for a position in the text going in a certain direction. (required) The base writing direction is set previously when the text input system sends a setBaseWritingDirection:forRange: message to the conforming document object.

Parameters:

  • position (UITextPosition) —

    An object that identifies a location in a document.

  • direction (UITextStorageDirection) —

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

Returns:

  • (UITextWritingDirection) —

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

- (CGRect) caretRectForPosition(position)

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

Parameters:

  • position (UITextPosition) —

    An object that identifies a location in a document.

Returns:

  • (CGRect) —

    A rectangle that defines the area for drawing the caret.

- (Integer) characterOffsetOfPosition(position, withinRange:range)

Return the character offset of a position in a document’s text that falls within a given range. 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.

Parameters:

  • position (UITextPosition) —

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

  • range (UITextRange) —

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

Returns:

  • (Integer) —

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

- (UITextRange) characterRangeAtPoint(point)

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

Parameters:

  • point (CGPoint) —

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

Returns:

  • (UITextRange) —

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

- (UITextRange) characterRangeByExtendingPosition(position, inDirection:direction)

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

Parameters:

  • position (UITextPosition) —

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

  • direction (UITextLayoutDirection) —

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

Returns:

  • (UITextRange) —

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

- (UITextPosition) closestPositionToPoint(point)

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

Parameters:

  • point (CGPoint) —

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

Returns:

  • (UITextPosition) —

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

- (UITextPosition) closestPositionToPoint(point, withinRange:range)

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

Parameters:

  • point (CGPoint) —

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

  • range (UITextRange) —

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

Returns:

  • (UITextPosition) —

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

- (NSComparisonResult) comparePosition(position, toPosition:other)

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

Parameters:

  • position (UITextPosition) —

    A custom object that represents a location within a document.

  • other (UITextPosition) —

    A custom object that represents another location within a document.

Returns:

  • (NSComparisonResult) —

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

- (Object) dictationRecognitionFailed

Called when dictation ended but recognition failed. Implement this optional method if you want to respond to failed dictation recognition.

Returns:

- (Object) dictationRecordingDidEnd

Called when there is a pending dictation result. Implement this optional method if you want to respond to the completion of the recognition of a dictated phrase.

Returns:

- (CGRect) firstRectForRange(range)

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

Parameters:

  • range (UITextRange) —

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

Returns:

  • (CGRect) —

    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.

- (CGRect) frameForDictationResultPlaceholder(placeholder)

Asks for the rectangle in which to display the dictation placeholder animation. 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).

Parameters:

  • placeholder (Object) —

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

Returns:

  • (CGRect) —

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

- (Object) insertDictationResult(dictationResult)

Called when there is more than one interpretation of a spoken phrase in a dictation result. 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.

Parameters:

Returns:

- (Object) insertDictationResultPlaceholder

Asks for the placeholder object to use while dictation results are being generated. 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.

Returns:

  • (Object) —

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

- (Integer) offsetFromPosition(fromPosition, toPosition:toPosition)

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

Parameters:

  • fromPosition (UITextPosition) —

    A custom object that represents a location within a document.

  • toPosition (UITextPosition) —

    A custom object that represents another location within document.

Returns:

  • (Integer) —

    The number of visible characters between fromPosition and toPosition.

- (UITextPosition) positionFromPosition(position, inDirection:direction, offset:offset)

Returns the text position at a given offset in a specified direction from another text position. (required) For an example of an implementation of the related method, positionFromPosition:offset:, see “Drawing and Managing Text”“ in Text, Web, and Editing Programming Guide for iOS.

Parameters:

  • position (UITextPosition) —

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

  • direction (UITextLayoutDirection) —

    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 (Integer) —

    A character offset from position.

Returns:

- (UITextPosition) positionFromPosition(position, offset:offset)

Returns the text position at a given offset from another text position. (required) For an example of an implementation of this method, see “Drawing and Managing Text” in Text, Web, and Editing Programming Guide for iOS.

Parameters:

  • position (UITextPosition) —

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

  • offset (Integer) —

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

Returns:

  • (UITextPosition) —

    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.

- (UITextPosition) positionWithinRange(range, atCharacterOffset:offset)

Return the position within a range of a document’s text that corresponds to the character offset from the start of that range. 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.

Parameters:

  • range (UITextRange) —

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

  • offset (Integer) —

    A character offset from the start of range.

Returns:

  • (UITextPosition) —

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

- (UITextPosition) positionWithinRange(range, farthestInDirection:direction)

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

Parameters:

  • range (UITextRange) —

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

  • direction (UITextLayoutDirection) —

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

Returns:

  • (UITextPosition) —

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

- (Object) removeDictationResultPlaceholder(placeholder, willInsertResult:willInsertResult)

Tells the view that the specified placeholder object is no longer needed. 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.

Parameters:

  • placeholder (Object) —

    The placeholder object that is no longer needed.

  • willInsertResult (Boolean) —

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

Returns:

- (Object) replaceRange(range, withText:text)

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

Parameters:

  • range (UITextRange) —

    A range of text in a document.

  • text (String) —

    A string to replace the text in range.

Returns:

- (Array) selectionRectsForRange(range)

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

Parameters:

  • range (UITextRange) —

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

Returns:

- (Object) setBaseWritingDirection(writingDirection, forRange:range)

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

Parameters:

  • writingDirection (UITextWritingDirection) —

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

  • range (UITextRange) —

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

Returns:

- (Object) setMarkedText(markedText, selectedRange:selectedRange)

Insert the provided text and marks it to indicate that it is part of an active input session. (required) Setting marked text either replaces the existing marked text or, if none is present, inserts it in place of the current selection.

Parameters:

  • markedText (String) —

    The text to be marked.

  • selectedRange (NSRange) —

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

Returns:

- (Boolean) shouldChangeTextInRange(range, replacementText:text)

Asks whether the text in the specified range should be replaced. 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.

Parameters:

  • range (UITextRange) —

    A range of text in a document.

  • text (String) —

    The proposed text to replace the text in range.

Returns:

  • (Boolean) —

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

- (String) textInRange(range)

Return the text in the specified range. (required)

Parameters:

  • range (UITextRange) —

    A range of text in a document.

Returns:

  • (String) —

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

- (UITextRange) textRangeFromPosition(fromPosition, toPosition:toPosition)

Return the range between two text positions. (required)

Parameters:

  • fromPosition (UITextPosition) —

    An object that represents a location in a document.

  • toPosition (UITextPosition) —

    An object that represents another location in a document.

Returns:

  • (UITextRange) —

    An object that represents the range between fromPosition and toPosition.

- (Hash) textStylingAtPosition(position, inDirection:direction)

Return a dictionary with properties that specify how text is to be style at a certain location in a document. Text styling information can affect, for example, the appearance of a correction rectangle.

Parameters:

  • position (UITextPosition) —

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

  • direction (UITextStorageDirection) —

    The direction of the styling attributes in text storage.

Returns:

  • (Hash) —

    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.

- (Object) unmarkText

Unmark the currently marked text. (required) After this method is called, the value of markedTextRange is nil.

Returns: