iOS Developer Library — Pre-Release

Developer

UIKit Framework Reference UITextView Class Reference

Options
Deployment Target:

On This Page
Language:

UITextView

Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.

The UITextView class implements the behavior for a scrollable, multiline text region. The class supports the display of text using custom style information and also supports text editing. You typically use a text view to display multiple lines of text, such as when displaying the body of a large text document.

In iOS 6 and later, this class supports multiple text styles through use of the attributedText property. (Styled text is not supported in earlier versions of iOS.) Setting a value for this property causes the text view to use the style information provided in the attributed string. You can still use the font, textColor, and textAlignment properties to set style attributes, but those properties apply to all of the text in the text view.

For information about basic view behaviors, see View Programming Guide for iOS.

Managing the Keyboard

When the user taps in an editable text view, that text view becomes the first responder and automatically asks the system to display the associated keyboard. Because the appearance of the keyboard has the potential to obscure portions of your user interface, it is up to you to make sure that does not happen by repositioning any views that might be obscured. Some system views, like table views, help you by scrolling the first responder into view automatically. If the first responder is at the bottom of the scrolling region, however, you may still need to resize or reposition the scroll view itself to ensure the first responder is visible.

It is your application’s responsibility to dismiss the keyboard at the time of your choosing. You might dismiss the keyboard in response to a specific user action, such as the user tapping a particular button in your user interface. To dismiss the keyboard, send the resignFirstResponder message to the text view that is currently the first responder. Doing so causes the text view object to end the current editing session (with the delegate object’s consent) and hide the keyboard.

The appearance of the keyboard itself can be customized using the properties provided by the UITextInputTraits protocol. Text view objects implement this protocol and support the properties it defines. You can use these properties to specify the type of keyboard (ASCII, Numbers, URL, Email, and others) to display. You can also configure the basic text entry behavior of the keyboard, such as whether it supports automatic capitalization and correction of the text.

Keyboard Notifications

When the system shows or hides the keyboard, it posts several keyboard notifications. These notifications contain information about the keyboard, including its size, which you can use for calculations that involve repositioning or resizing views. Registering for these notifications is the only way to get some types of information about the keyboard. The system delivers the following notifications for keyboard-related events:

For more information about these notifications, see their descriptions in UIWindow Class Reference.

State Preservation

In iOS 6 and later, if you assign a value to this view’s restorationIdentifier property, it preserves the following information:

  • The selected range of text, as reported by the selectedRange property.

  • The editing state of the text view, as reported by the editable property.

During the next launch cycle, the view attempts to restore these properties to their saved values. If the selection range cannot be applied to the text in the restored view, no text is selected. For more information about how state preservation and restoration works, see App Programming Guide for iOS.

For more information about appearance and behavior configuration, see Text Views.

  • Creates a new text view with the specified text container.

    Declaration

    Swift

    init(frame frame: CGRect, textContainer textContainer: NSTextContainer?)

    Objective-C

    - (instancetype)initWithFrame:(CGRect)frame textContainer:(NSTextContainer *)textContainer

    Parameters

    frame

    The frame rectangle of the text view.

    textContainer

    The text container to use for the receiver (can be nil).

    Return Value

    An initialized text view.

    Discussion

    This is the designated initializer for UITextView objects.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • text text Property

    The text displayed by the text view.

    Declaration

    Swift

    var text: String!

    Objective-C

    @property(nonatomic, copy) NSString *text

    Discussion

    In iOS 6 and later, assigning a new value to this property also replaces the value of the attributedText property with the same text, albeit without any inherent style attributes. Instead the text view styles the new string using the font, textColor, and other style-related properties of the class.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    attributedText

  • The styled text displayed by the text view.

    Declaration

    Swift

    @NSCopying var attributedText: NSAttributedString!

    Objective-C

    @property(nonatomic, copy) NSAttributedString *attributedText

    Discussion

    This property is nil by default. Assigning a new value to this property also replaces the value of the text property with the same string data, albeit without any formatting information. In addition, assigning a new a value updates the values in the font, textColor, and textAlignment properties so that they reflect the style information starting at location 0 in the attributed string.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • font font Property

    The font of the text.

    Declaration

    Swift

    var font: UIFont!

    Objective-C

    @property(nonatomic, retain) UIFont *font

    Discussion

    This property applies to the entire text string. The default font is a 17-point Helvetica plain font.

    In iOS 6 and later, assigning a new value to this property causes the new font to be applied to the entire contents of the text view. If you want to apply the font to only a portion of the text, you must create a new attributed string with the desired style information and assign it to the attributedText property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • textColor textColor Property

    The color of the text.

    Declaration

    Swift

    var textColor: UIColor!

    Objective-C

    @property(nonatomic, retain) UIColor *textColor

    Discussion

    This property applies to the entire text string. The default text color is black.

    In iOS 6 and later, assigning a new value to this property causes the new text color to be applied to the entire contents of the text view. If you want to apply the color to only a portion of the text, you must create a new attributed string with the desired style information and assign it to the attributedText property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    backgroundColor (UIView)

  • editable editable Property

    A Boolean value indicating whether the receiver is editable.

    Declaration

    Swift

    var editable: Bool

    Objective-C

    @property(nonatomic, getter=isEditable) BOOL editable

    Discussion

    The default value of this property is YEStrue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether the text view allows the user to edit style information.

    Declaration

    Swift

    var allowsEditingTextAttributes: Bool

    Objective-C

    @property(nonatomic) BOOL allowsEditingTextAttributes

    Discussion

    When set to YEStrue, the text view allows the user to change the basic styling of the currently selected text. The available style options are listed in the edit menu and only apply to the selection.

    The default value of this property is NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • The types of data converted to clickable URLs in the text view.

    Declaration

    Swift

    var dataDetectorTypes: UIDataDetectorTypes

    Objective-C

    @property(nonatomic) UIDataDetectorTypes dataDetectorTypes

    Discussion

    You can use this property to specify the types of data (phone numbers, http links, and so on) that should be automatically converted to clickable URLs in the text view. When clicked, the text view opens the application responsible for handling the URL type and passes it the URL.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • The technique to use for aligning the text.

    Declaration

    Swift

    var textAlignment: NSTextAlignment

    Objective-C

    @property(nonatomic) NSTextAlignment textAlignment

    Discussion

    This property applies to the entire text string. The default value of this property is NSTextAlignmentLeft.

    In iOS 6 and later, assigning a new value to this property causes the new text alignment to be applied to the entire contents of the text view. If you want to apply the alignment to only a portion of the text, you must create a new attributed string with the desired style information and assign it to the attributedText property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • hasText - hasText Available in iOS 2.0 through iOS 6.1

    Returns a Boolean value indicating whether the text view currently contains any text.

    Declaration

    Objective-C

    - (BOOL)hasText

    Return Value

    YEStrue if the receiver contains text or NOfalse if it does not.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 2.0 through iOS 6.1.

  • The attributes to apply to new text being entered by the user.

    Declaration

    Swift

    var typingAttributes: [NSObject : AnyObject]!

    Objective-C

    @property(nonatomic, copy) NSDictionary *typingAttributes

    Discussion

    This dictionary contains the attribute keys (and corresponding values) to apply to newly typed text. When the text view’s selection changes, the contents of the dictionary are cleared automatically.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

    See Also

    editable

  • The attributes to apply to links.

    Declaration

    Swift

    var linkTextAttributes: [NSObject : AnyObject]!

    Objective-C

    @property(nonatomic, copy) NSDictionary *linkTextAttributes

    Discussion

    The default attributes specify blue text with a single underline and the pointing hand cursor.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The inset of the text container's layout area within the text view's content area.

    Declaration

    Swift

    var textContainerInset: UIEdgeInsets

    Objective-C

    @property(nonatomic, assign) UIEdgeInsets textContainerInset

    Discussion

    This property provides text margins for text laid out in the text view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The current selection range of the receiver.

    Declaration

    Swift

    var selectedRange: NSRange

    Objective-C

    @property(nonatomic) NSRange selectedRange

    Discussion

    In iOS 2.2 and earlier, the length of the selection range is always 0, indicating that the selection is actually an insertion point. In iOS 3.0 and later, the length of the selection range may be non-zero.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Scrolls the receiver until the text in the specified range is visible.

    Declaration

    Swift

    func scrollRangeToVisible(_ range: NSRange)

    Objective-C

    - (void)scrollRangeToVisible:(NSRange)range

    Parameters

    range

    The range of text to scroll into view.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether inserting text replaces the previous contents.

    Declaration

    Swift

    var clearsOnInsertion: Bool

    Objective-C

    @property(nonatomic) BOOL clearsOnInsertion

    Discussion

    The default value of this property is NOfalse. When the value of this property is YEStrue and the text view is in editing mode, the selection UI is hidden and inserting new text clears the contents of the text view and sets the value of this property back to NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • A Boolean value indicating whether the receiver is selectable.

    Declaration

    Swift

    var selectable: Bool

    Objective-C

    @property(nonatomic, getter=isSelectable) BOOL selectable

    Discussion

    This property controls the ability of the user to select content and interact with URLs and text attachments. The default value is YEStrue.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • delegate delegate Property

    The receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: UITextViewDelegate?

    Objective-C

    @property(nonatomic, assign) id< UITextViewDelegate > delegate

    Discussion

    A text view delegate responds to editing-related messages from the text view. You can use the delegate to track changes to the text itself and to the current selection.

    For information about the methods implemented by the delegate, see UITextViewDelegate Protocol Reference.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • inputView inputView Property

    The custom input view to display when the text view becomes the first responder.

    Declaration

    Swift

    var inputView: UIView?

    Objective-C

    @property(readwrite, retain) UIView *inputView

    Discussion

    If the value in this property is nil, the text view displays the standard system keyboard when it becomes first responder. Assigning a custom view to this property causes that view to be presented instead.

    The default value of this property is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • The custom accessory view to display when the text view becomes the first responder

    Declaration

    Swift

    var inputAccessoryView: UIView?

    Objective-C

    @property(readwrite, retain) UIView *inputAccessoryView

    Discussion

    The default value of this property is nil. Assigning a view to this property causes that view to be displayed above the standard system keyboard (or above the custom input view if one is provided) when the text view becomes the first responder. For example, you could use this property to attach a custom toolbar to the keyboard.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.2 and later.

    See Also

    inputView

  • The layout manager that lays out text for the receiver’s text container. (read-only)

    Declaration

    Swift

    var layoutManager: NSLayoutManager { get }

    Objective-C

    @property(nonatomic, readonly) NSLayoutManager *layoutManager

    Discussion

    This property is a convenience accessor that provides access through the text container.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The text container object defining the area in which text is displayed in this text view. (read-only)

    Declaration

    Swift

    var textContainer: NSTextContainer { get }

    Objective-C

    @property(nonatomic, readonly) NSTextContainer *textContainer

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The text storage object holding the text displayed in this text view. (read-only)

    Declaration

    Swift

    var textStorage: NSTextStorage { get }

    Objective-C

    @property(nonatomic, readonly, retain) NSTextStorage *textStorage

    Discussion

    This property is a convenience accessor that provides access through the text container.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.