iOS Developer Library

Developer

UIKit Framework Reference UITextInput Protocol Reference

Options
Deployment Target:

On This Page
Language:

UITextInput

Inheritance


Not Applicable

Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 3.2 and later.

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:

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

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.

  • Return the text in the specified range. (required)

    Declaration

    Swift

    func textInRange(_ range: UITextRange) -> String

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    func replaceRange(_ range: UITextRange, withText text: String)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    optional func shouldChangeTextInRange(_ range: UITextRange, replacementText text: String) -> Bool

    Objective-C

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

    YEStrue if the text should be changed or NOfalse 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 YEStrue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    @NSCopying var selectedTextRange: UITextRange? { get set }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

    See Also

    markedTextRange
    empty (UITextRange)

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

    Declaration

    Swift

    var markedTextRange: UITextRange? { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • markedTextStyle markedTextStyle Required Property

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

    Declaration

    Swift

    var markedTextStyle: [NSObject : AnyObject]! { get set }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    func setMarkedText(_ markedText: String!, selectedRange selectedRange: NSRange)

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Unmark the currently marked text. (required)

    Declaration

    Swift

    func unmarkText()

    Objective-C

    - (void)unmarkText

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • The desired location for the insertion point.

    Declaration

    Swift

    optional var selectionAffinity: UITextStorageDirection { get set }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • inputDelegate inputDelegate Required Property

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

    Declaration

    Swift

    unowned(unsafe) var inputDelegate: UITextInputDelegate! { get set }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • tokenizer tokenizer Property

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

    Declaration

    Swift

    var tokenizer: UITextInputTokenizer { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • Called when there is a pending dictation result.

    Declaration

    Swift

    optional func dictationRecordingDidEnd()

    Objective-C

    - (void)dictationRecordingDidEnd

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.1 and later.

  • Called when dictation ended but recognition failed.

    Declaration

    Swift

    optional func dictationRecognitionFailed()

    Objective-C

    - (void)dictationRecognitionFailed

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.1 and later.

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

    Declaration

    Swift

    optional func insertDictationResult(_ dictationResult: [AnyObject])

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.1 and later.

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

    Declaration

    Swift

    optional func insertDictationResultPlaceholder() -> AnyObject

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func frameForDictationResultPlaceholder(_ placeholder: AnyObject!) -> CGRect

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func removeDictationResultPlaceholder(_ placeholder: AnyObject, willInsertResult willInsertResult: Bool)

    Objective-C

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

    Parameters

    placeholder

    The placeholder object that is no longer needed.

    willInsertResult

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

    Discussion

    If the value in the willInsertResult parameter is NOfalse, 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.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    optional func textStylingAtPosition(_ position: UITextPosition, inDirection direction: UITextStorageDirection) -> [NSObject : AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    optional func positionWithinRange(_ range: UITextRange!, atCharacterOffset offset: Int) -> UITextPosition!

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    optional func characterOffsetOfPosition(_ position: UITextPosition, withinRange range: UITextRange) -> Int

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    optional var textInputView: UIView { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

Data Types

  • The direction of text storage.

    Declaration

    Swift

    enum UITextStorageDirection : Int { case Forward case Backward }

    Objective-C

    typedef enum { UITextStorageDirectionForward = 0, UITextStorageDirectionBackward } UITextStorageDirection;

    Constants

    • Forward

      UITextStorageDirectionForward

      Storage of the text in a forward direction.

      Available in iOS 3.2 and later.

    • Backward

      UITextStorageDirectionBackward

      Storage of the text in a backward direction.

      Available in iOS 3.2 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • The direction of text layout.

    Declaration

    Swift

    enum UITextLayoutDirection : Int { case Right case Left case Up case Down }

    Objective-C

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

    Constants

    • Right

      UITextLayoutDirectionRight

      Layout of the text to the right.

      Available in iOS 3.2 and later.

    • Left

      UITextLayoutDirectionLeft

      Layout of the text to the left.

      Available in iOS 3.2 and later.

    • Up

      UITextLayoutDirectionUp

      Layout of the text in an upward direction.

      Available in iOS 3.2 and later.

    • Down

      UITextLayoutDirectionDown

      Layout of the text in a downward direction.

      Available in iOS 3.2 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • The writing direction of the text, based on language.

    Declaration

    Swift

    enum UITextWritingDirection : Int { case Natural case LeftToRight case RightToLeft }

    Objective-C

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

    Constants

    • Natural

      UITextWritingDirectionNatural

      The natural writing direction as defined by the Bidi algorithm.

      Available in iOS 3.2 and later.

    • LeftToRight

      UITextWritingDirectionLeftToRight

      Writing that goes from left to right.

      Available in iOS 3.2 and later.

    • RightToLeft

      UITextWritingDirectionRightToLeft

      Writing that goes from right to left.

      Available in iOS 3.2 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • A dictionary containing properties that define text style characteristics.

    Declaration

    Swift

    let UITextInputTextBackgroundColorKey: String let UITextInputTextColorKey: String let UITextInputTextFontKey: String

    Objective-C

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

    Constants

    • UITextInputTextBackgroundColorKey

      UITextInputTextBackgroundColorKey

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

      Available in iOS 3.2 and later.

      Deprecated in iOS 8.0.

    • UITextInputTextColorKey

      UITextInputTextColorKey

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

      Available in iOS 3.2 and later.

      Deprecated in iOS 8.0.

    • UITextInputTextFontKey

      UITextInputTextFontKey

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

      Available in iOS 3.2 and later.

      Deprecated in iOS 8.0.

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