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:
UITextPositionandUITextRangeclasses—AllUITextInput-conforming document classes must create custom subclasses of these classes. A UITextPosition object represents a position in a text container. AUITextRangeobject, which encapsulates beginning and endingUITextPositionobjects, represents a range of characters in the text container.UITextInputTokenizerprotocol andUITextInputStringTokenizerclass—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.UITextInputDelegateprotocol—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.UIKeyInputprotocol—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.
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
-
– textInRange:required method -
– replaceRange:withText:required method -
– shouldChangeTextInRange:replacementText:
Working with Marked and Selected Text
-
selectedTextRangerequired property -
markedTextRangerequired property -
markedTextStylerequired property -
– setMarkedText:selectedRange:required method -
– unmarkTextrequired method -
selectionAffinityproperty
Computing Text Ranges and Text Positions
-
– textRangeFromPosition:toPosition:required method -
– positionFromPosition:offset:required method -
– positionFromPosition:inDirection:offset:required method -
beginningOfDocumentrequired property -
endOfDocumentrequired property
Evaluating Text Positions
-
– comparePosition:toPosition:required method -
– offsetFromPosition:toPosition:required method
Determining Layout and Writing Direction
-
– positionWithinRange:farthestInDirection: -
– characterRangeByExtendingPosition:inDirection:required method -
– baseWritingDirectionForPosition:inDirection:required method -
– setBaseWritingDirection:forRange:required method
Geometry and Hit-Testing Methods
-
– firstRectForRange:required method -
– caretRectForPosition:required method -
– closestPositionToPoint:required method -
– selectionRectsForRange:required method -
– closestPositionToPoint:withinRange:required method -
– characterRangeAtPoint:required method
Text Input Delegate and Text Input Tokenizer
-
inputDelegaterequired property -
tokenizerrequired property
Using Dictation
-
– dictationRecordingDidEnd -
– dictationRecognitionFailed -
– insertDictationResult: -
– insertDictationResultPlaceholder -
– frameForDictationResultPlaceholder: -
– removeDictationResultPlaceholder:willInsertResult:
Returning Text Styling Information
Reconciling Text Position and Character Offset
Returning the Text Input View
-
textInputViewproperty
Properties
beginningOfDocument
The text position for the beginning of a document. (required) (read-only)
Availability
- Available in iOS 3.2 and later.
See Also
Declared In
UITextInput.hendOfDocument
The text position for the end of a document. (required) (read-only)
Availability
- Available in iOS 3.2 and later.
See Also
Declared In
UITextInput.hinputDelegate
An input delegate that is notified when text changes or when the selection changes. (required)
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.hmarkedTextRange
The range of text that is currently marked in a document. (required) (read-only)
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.hmarkedTextStyle
A dictionary of attributes that describes how marked text should be drawn. (required)
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.hselectedTextRange
The range of selected text in a document. (required)
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
-
@property markedTextRange -
empty(UITextRange)
Declared In
UITextInput.hselectionAffinity
The desired location for the insertion point.
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.htextInputView
An affiliated view that provides a coordinate system for all geometric values in this protocol. (read-only)
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.htokenizer
An input tokenizer that provides information about the granularity of text units. (required) (read-only)
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.hInstance Methods
baseWritingDirectionForPosition:inDirection:
Return the base writing direction for a position in the text going in a certain direction. (required)
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.hcaretRectForPosition:
Return a rectangle used to draw the caret at a given insertion point. (required)
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.
See Also
Declared In
UITextInput.hcharacterOffsetOfPosition:withinRange:
Return the character offset of a position in a document’s text that falls within a given 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.hcharacterRangeAtPoint:
Return the character or range of characters that is at a given point in a document. (required)
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.hcharacterRangeByExtendingPosition:inDirection:
Return a text range from a given text position to its farthest extent in a certain direction of layout. (required)
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.hclosestPositionToPoint:
Return the position in a document that is closest to a specified point. (required)
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.hclosestPositionToPoint:withinRange:
Return the position in a document that is closest to a specified point in a given range. (required)
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.hcomparePosition:toPosition:
Return how one text position compares to another text position. (required)
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.
See Also
Declared In
UITextInput.hdictationRecognitionFailed
Called when dictation ended but recognition failed.
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.hdictationRecordingDidEnd
Called when there is a pending dictation result.
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.hfirstRectForRange:
Return the first rectangle that encloses a range of text in a document. (required)
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.
See Also
Declared In
UITextInput.hframeForDictationResultPlaceholder:
Asks for the rectangle in which to display the dictation placeholder animation.
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.hinsertDictationResult:
Called when there is more than one interpretation of a spoken phrase in a dictation result.
Parameters
- dictationResult
An array of
UIDictationPhraseobjects.
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.hinsertDictationResultPlaceholder
Asks for the placeholder object to use while dictation results are being generated.
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.hoffsetFromPosition:toPosition:
Return the number of visible characters between one text position and another text position. (required)
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.
See Also
Declared In
UITextInput.hpositionFromPosition:inDirection:offset:
Returns the text position at a given offset in a specified direction from another text position. (required)
Parameters
- position
A custom
UITextPositionobject that represents a location in a document.- direction
A
UITextLayoutDirectionconstant that represents the direction of the offset from position. Returnnilif 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, Web, and Editing Programming Guide for iOS.
Availability
- Available in iOS 3.2 and later.
Declared In
UITextInput.hpositionFromPosition:offset:
Returns the text position at a given offset from another text position. (required)
Parameters
- position
A custom
UITextPositionobject 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, Web, and Editing Programming Guide for iOS.
Availability
- Available in iOS 3.2 and later.
Declared In
UITextInput.hpositionWithinRange:atCharacterOffset:
Return the position within a range of a document’s text that corresponds to the character offset from the start of that range.
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.hpositionWithinRange:farthestInDirection:
Return the text position that is at the farthest extent in a given layout direction within a range of text.
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.hremoveDictationResultPlaceholder:willInsertResult:
Tells the view that the specified placeholder object is no longer needed.
Parameters
- placeholder
The placeholder object that is no longer needed.
- willInsertResult
The value of this parameter is
YESif the dictation value was generated successfully orNOif 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.hreplaceRange:withText:
Replace the text in a document that is in the specified range. (required)
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.
See Also
Declared In
UITextInput.hselectionRectsForRange:
Returns an array of selection rects corresponding to the range of text. (required)
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.hsetBaseWritingDirection:forRange:
Set the base writing direction for a given range of text in a document. (required)
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.hsetMarkedText:selectedRange:
Insert the provided text and marks it to indicate that it is part of an active input session. (required)
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.hshouldChangeTextInRange:replacementText:
Asks whether the text in the specified range should be replaced.
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.htextInRange:
Return the text in the specified range. (required)
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.
See Also
Declared In
UITextInput.htextRangeFromPosition:toPosition:
Return the range between two text positions. (required)
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.htextStylingAtPosition:inDirection:
Return a dictionary with properties that specify how text is to be style at a certain location in a document.
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.hunmarkText
Unmark the currently marked text. (required)
Discussion
After this method is called, the value of markedTextRange is nil.
Availability
- Available in iOS 3.2 and later.
Declared In
UITextInput.hConstants
UITextStorageDirection
The direction of text storage.
typedef enum {
UITextStorageDirectionForward = 0,
UITextStorageDirectionBackward
} UITextStorageDirection;
Constants
UITextStorageDirectionForwardStorage of the text in a forward direction.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextStorageDirectionBackwardStorage 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.hUITextLayoutDirection
The direction of text layout.
typedef enum {
UITextLayoutDirectionRight = 2,
UITextLayoutDirectionLeft,
UITextLayoutDirectionUp,
UITextLayoutDirectionDown
} UITextLayoutDirection;
Constants
UITextLayoutDirectionRightLayout of the text to the right.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextLayoutDirectionLeftLayout of the text to the left.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextLayoutDirectionUpLayout of the text in an upward direction.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextLayoutDirectionDownLayout of the text in a downward direction.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.
Discussion
Constants of this type are used as arguments in the positionFromPosition:inDirection:offset:, positionWithinRange:farthestInDirection:, and characterRangeByExtendingPosition:inDirection: methods.
Availability
- Available in iOS 3.2 and later.
Declared In
UITextInput.hUITextWritingDirection
The writing direction of the text, based on language.
typedef enum {
UITextWritingDirectionNatural = -1,
UITextWritingDirectionLeftToRight = 0,
UITextWritingDirectionRightToLeft,
} UITextWritingDirection;
Constants
UITextWritingDirectionNaturalThe natural writing direction as defined by the Bidi algorithm.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextWritingDirectionLeftToRightWriting that goes from left to right.
Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextWritingDirectionRightToLeftWriting 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.hStyle Dictionary Keys
A dictionary containing properties that define text style characteristics.
NSString *const UITextInputTextBackgroundColorKey; NSString *const UITextInputTextColorKey; NSString *const UITextInputTextFontKey;
Constants
UITextInputTextBackgroundColorKeyThe background color of the text. The value of this key is a
UIColorobject.Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextInputTextColorKeyThe color of the text. The value of this key is a
UIColorobject.Available in iOS 3.2 and later.
Declared in
UITextInput.h.UITextInputTextFontKeyThe font of the text. The value of this key is a
UIFontobject.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).
© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)