Class RadTextBoxControl

Represents a text box control that enables users to enter and edit text with support for multiline editing, auto-completion, and advanced text manipulation features. This control serves as a wrapper around RadTextBoxControlElement and provides comprehensive text input functionality including password masking, scrolling, and data binding capabilities.

Inheritance
System.Object
RadControl
RadTextBoxControl
RadAutoCompleteBox
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

[TelerikToolboxCategory("Editors")]
[ClassInterface(ClassInterfaceType.AutoDispatch)]
[ComVisible(true)]
public class RadTextBoxControl : RadControl, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider

Constructors

RadTextBoxControl()

Initializes a new instance of the RadTextBoxControl class. Sets up the control styles and registers the initialization event handler for deferred property setting.

Declaration
public RadTextBoxControl()

Properties

AcceptsReturn

Gets or sets a value indicating whether pressing ENTER creates a new line instead of activating the default button. When true in a multiline text box, ENTER keypresses create new lines; when false, they activate the form's default button.

Declaration
public bool AcceptsReturn { get; set; }
Property Value
System.Boolean

AcceptsTab

Gets or sets a value indicating whether pressing the TAB key inserts a tab character instead of moving focus. When true in a multiline text box, TAB keypresses insert tab characters; when false, they move focus to the next control.

Declaration
public bool AcceptsTab { get; set; }
Property Value
System.Boolean

AutoCompleteDataSource

Gets or sets the data source that provides auto-complete suggestions. This property specifies the collection or data source used to populate auto-complete items for text suggestions.

Declaration
public object AutoCompleteDataSource { get; set; }
Property Value
System.Object

AutoCompleteDisplayMember

Gets or sets the property name to use as the display member for auto-complete items. This property determines which field from the AutoCompleteDataSource is displayed as suggestion text.

Declaration
public string AutoCompleteDisplayMember { get; set; }
Property Value
System.String

AutoCompleteItems

Gets the collection of auto-complete items used for text suggestions. This property provides direct access to the items collection for adding, removing, or modifying suggestion entries.

Declaration
public RadListDataItemCollection AutoCompleteItems { get; }
Property Value
RadListDataItemCollection

AutoCompleteMode

Gets or sets the auto-completion mode that controls how automatic text completion works. This property determines whether suggestions are displayed in a dropdown, appended to the text, or both.

Declaration
public virtual AutoCompleteMode AutoCompleteMode { get; set; }
Property Value
System.Windows.Forms.AutoCompleteMode

AutoSize

Gets or sets a value indicating whether the control automatically resizes its height to display all content. For RadTextBoxControl, AutoSize affects only the height dimension and adjusts based on font size and content.

Declaration
public override bool AutoSize { get; set; }
Property Value
System.Boolean

Overrides

CaretIndex

Gets or sets the position of the text cursor (caret) within the text. This property represents the zero-based index of the character position where text insertion occurs.

Declaration
public int CaretIndex { get; set; }
Property Value
System.Int32

CharacterCasing

Gets or sets how the case of typed characters is modified automatically. This property allows forcing text to uppercase, lowercase, or preserving the original case as typed.

Declaration
public CharacterCasing CharacterCasing { get; set; }
Property Value
System.Windows.Forms.CharacterCasing

DefaultSize

Gets the default size of the text box control.

Declaration
protected override Size DefaultSize { get; }
Property Value
System.Drawing.Size

A System.Drawing.Size structure representing the default dimensions of the control (125x22 pixels).

DropDownMaxSize

Gets or sets the maximum size of the auto-complete dropdown list. This property controls the largest allowable dimensions for the dropdown that displays auto-complete suggestions.

Declaration
public Size DropDownMaxSize { get; set; }
Property Value
System.Drawing.Size

DropDownMinSize

Gets or sets the minimum size of the auto-complete dropdown list. This property controls the smallest allowable dimensions for the dropdown that displays auto-complete suggestions.

Declaration
public Size DropDownMinSize { get; set; }
Property Value
System.Drawing.Size

EmbeddedLabelText

Gets or sets the text displayed in the embedded label. This property controls the content of the label that appears when ShowEmbeddedLabel is enabled.

Declaration
public string EmbeddedLabelText { get; set; }
Property Value
System.String

HideSelection

Gets or sets a value indicating whether selected text remains highlighted when the control loses focus. When true, selected text highlighting is hidden when focus moves away from the control; when false, selection remains visible.

Declaration
public bool HideSelection { get; set; }
Property Value
System.Boolean

HorizontalScrollBarState

Gets or sets when the horizontal scroll bar should appear in a multiline text box. This property controls the visibility behavior of the horizontal scrollbar based on content overflow.

Declaration
public ScrollState HorizontalScrollBarState { get; set; }
Property Value
ScrollState

ImageList

This property is not relevant for this class.

Declaration
public override ImageList ImageList { get; set; }
Property Value
System.Windows.Forms.ImageList

Overrides

IsReadOnly

Gets or sets a value indicating whether the text box is in read-only mode, preventing user text modification. When true, users can select and copy text but cannot edit the content; when false, full editing is allowed.

Declaration
public bool IsReadOnly { get; set; }
Property Value
System.Boolean

IsReadOnlyCaretVisible

Gets or sets a value indicating whether the text cursor is visible when the control is in read-only mode. When true, the caret remains visible in read-only mode; when false, no cursor is shown.

Declaration
public bool IsReadOnlyCaretVisible { get; set; }
Property Value
System.Boolean

Lines

Gets or sets the lines of text in the text box as an array of strings. Each array element represents a separate line, allowing programmatic access to multiline text content.

Declaration
public string[] Lines { get; set; }
Property Value
System.String[]

ListElement

Gets the auto-complete list element that displays suggestion items. This property provides access to the dropdown list that shows auto-complete suggestions to the user.

Declaration
public RadTextBoxListElement ListElement { get; }
Property Value
RadTextBoxListElement

MaxDropDownItemCount

Gets or sets the maximum number of visible items in the auto-complete dropdown list. This property determines how many suggestion items are displayed simultaneously before scrolling is required.

Declaration
public int MaxDropDownItemCount { get; set; }
Property Value
System.Int32

MaxLength

Gets or sets the maximum number of characters that can be entered or pasted into the text box. When set to a value other than System.Int32.MaxValue, input is limited to this character count.

Declaration
public int MaxLength { get; set; }
Property Value
System.Int32

Multiline

Gets or sets a value indicating whether the text box supports multiple lines of text. When true, the control can display and accept multiple lines with line breaks; when false, only single-line text is supported.

Declaration
public bool Multiline { get; set; }
Property Value
System.Boolean

NullText

Gets or sets the placeholder text displayed when the text box is empty and does not have focus. This text provides users with hints about the expected input format or content.

Declaration
public string NullText { get; set; }
Property Value
System.String

NullTextColor

Gets or sets the color of the placeholder text displayed when the text box is empty. This property controls the visual appearance of the NullText when shown to users.

Declaration
public Color NullTextColor { get; set; }
Property Value
System.Drawing.Color

PasswordChar

Gets or sets the character used to mask password characters in single-line text entry. When set to a non-null character, all typed characters will be displayed as this masking character for secure password input.

Declaration
public virtual char PasswordChar { get; set; }
Property Value
System.Char

RadContextMenu

Gets or sets the context menu associated with this text box control. This property provides access to the right-click menu that appears when users right-click on the text box.

Declaration
public virtual RadContextMenu RadContextMenu { get; set; }
Property Value
RadContextMenu

A RadContextMenu that represents the shortcut menu associated with the control.

SelectedText

Gets or sets the currently selected text within the text box control. This property allows reading the selected text or replacing the selection with new text content.

Declaration
public string SelectedText { get; set; }
Property Value
System.String

SelectionColor

Gets or sets the background color used for selected text within the text box. This property controls the highlight color that appears behind selected text characters.

Declaration
public Color SelectionColor { get; set; }
Property Value
System.Drawing.Color

SelectionLength

Gets or sets the number of characters in the current text selection. This property determines how many characters from the SelectionStart position are selected.

Declaration
public int SelectionLength { get; set; }
Property Value
System.Int32

SelectionOpacity

Gets or sets the opacity level of the text selection highlighting. This property controls the transparency of the selection background color, with values from 0 (fully transparent) to 100 (fully opaque).

Declaration
public int SelectionOpacity { get; set; }
Property Value
System.Int32

SelectionStart

Gets or sets the starting position of the text selection within the text box. This property represents the zero-based index where the text selection begins.

Declaration
public int SelectionStart { get; set; }
Property Value
System.Int32

ShowClearButton

Gets or sets a value indicating whether the clear button is displayed within the text box. When enabled, users can click the clear button to quickly remove all text from the control.

Declaration
public bool ShowClearButton { get; set; }
Property Value
System.Boolean

ShowEmbeddedLabel

Gets or sets a value indicating whether the embedded label is displayed within the text box. When enabled, the embedded label provides descriptive text that appears alongside the input area. It is recommended to set System.Windows.Forms.Control.AutoSize to true when using the embedded label.

Declaration
public bool ShowEmbeddedLabel { get; set; }
Property Value
System.Boolean

ShowNullText

Gets or sets a value indicating whether the placeholder text remains visible when the control has focus and the text is empty. When true, NullText is displayed even when the control is focused; when false, it disappears on focus.

Declaration
public bool ShowNullText { get; set; }
Property Value
System.Boolean

Text

Gets or sets the text content displayed in the text box control. This property contains the actual text that users can view and edit within the control.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides

TextAlign

Gets or sets the horizontal alignment of text within the text box control. This property determines whether text is aligned to the left, center, or right within the control's bounds.

Declaration
public HorizontalAlignment TextAlign { get; set; }
Property Value
System.Windows.Forms.HorizontalAlignment

TextBoxElement

Gets the associated text box element that provides the core text editing functionality. This property provides access to the underlying RadTextBoxControlElement for advanced customization scenarios.

Declaration
public RadTextBoxControlElement TextBoxElement { get; }
Property Value
RadTextBoxControlElement

TextLength

Gets the total length of text currently contained in the text box. This property returns the number of characters in the System.Windows.Forms.Control.Text property.

Declaration
public int TextLength { get; }
Property Value
System.Int32

UseSystemPasswordChar

Gets or sets a value indicating whether the text should be displayed using the system's default password character. When enabled, all characters in the text box are masked with the system password character for secure input.

Declaration
public virtual bool UseSystemPasswordChar { get; set; }
Property Value
System.Boolean

VerticalScrollBarState

Gets or sets when the vertical scroll bar should appear in a multiline text box. This property controls the visibility behavior of the vertical scrollbar based on content overflow.

Declaration
public ScrollState VerticalScrollBarState { get; set; }
Property Value
ScrollState

WordWrap

Gets or sets a value indicating whether text automatically wraps to the next line when it reaches the control's edge. When true in a multiline text box, long lines are broken at word boundaries; when false, horizontal scrolling is used instead.

Declaration
public bool WordWrap { get; set; }
Property Value
System.Boolean

Methods

AppendText(String)

Appends the specified text to the end of the current text content in the text box. This method adds new text without replacing existing content.

Declaration
public void AppendText(string text)
Parameters
System.String text

The text to append to the existing content.

Clear()

Removes all text content from the text box, making it empty. This method clears the entire Text property and resets the cursor position.

Declaration
public void Clear()

Copy()

Copies the currently selected text to the clipboard without removing it from the text box. The selected text remains in the control and is available for pasting elsewhere.

Declaration
public bool Copy()
Returns
System.Boolean

true if the copy operation was successful; otherwise, false.

CreateAccessibilityInstance()

Creates an accessibility object for this text box control to support assistive technologies. When EnableRadAccessibilityObjects is enabled, returns a custom accessibility object; otherwise, returns the base implementation.

Declaration
protected override AccessibleObject CreateAccessibilityInstance()
Returns
System.Windows.Forms.AccessibleObject

An System.Windows.Forms.AccessibleObject that provides accessibility support for this control.

CreateChildItems(RadElement)

Creates the child elements of the control by instantiating and configuring the internal RadTextBoxControlElement. This method sets up the text box element and establishes event handlers for text change notifications.

Declaration
protected override void CreateChildItems(RadElement parent)
Parameters
RadElement parent

The parent RadElement that will contain the child elements.
Overrides

CreateTextBoxElement()

Creates the associated text box element that provides the core text editing functionality. This method can be overridden in derived classes to provide custom text box element implementations.

Declaration
protected virtual RadTextBoxControlElement CreateTextBoxElement()
Returns
RadTextBoxControlElement

A new instance of RadTextBoxControlElement or a derived class.

Cut()

Cuts the currently selected text to the clipboard, removing it from the text box. This operation combines copying the selection and deleting it from the control.

Declaration
public bool Cut()
Returns
System.Boolean

true if the cut operation was successful; otherwise, false.

Delete()

Deletes the character at the current cursor position. This method removes one character from the text content at the caret location.

Declaration
public bool Delete()
Returns
System.Boolean

true if the delete operation was successful; otherwise, false.

Delete(Boolean)

Deletes a character at the current cursor position with directional control. This method can delete either the character before (backspace) or after (delete) the cursor.

Declaration
public bool Delete(bool nextCharacter)
Parameters
System.Boolean nextCharacter

true to delete the character after the cursor; false to delete the character before the cursor.
Returns
System.Boolean

true if the delete operation was successful; otherwise, false.

Delete(Boolean, Boolean)

Deletes text with advanced control over direction and word boundary behavior. When Control is pressed, deletion extends to word boundaries for faster text editing.

Declaration
public bool Delete(bool nextCharacter, bool isControlPressed)
Parameters
System.Boolean nextCharacter

true to delete the character or word after the cursor; false to delete before the cursor.
System.Boolean isControlPressed

true to delete to the end of the word; false to delete only a single character.
Returns
System.Boolean

true if the delete operation was successful; otherwise, false.

DeselectAll()

Clears the current text selection by setting the SelectionLength to zero. After calling this method, no characters will be selected in the text box.

Declaration
public bool DeselectAll()
Returns
System.Boolean

true if the selection was successfully cleared; otherwise, false.

Insert(String)

Inserts the specified text at the current cursor position or replaces the selected text. If text is selected, it will be replaced; otherwise, the text is inserted at the caret position.

Declaration
public bool Insert(string text)
Parameters
System.String text

The text to insert into the text box.
Returns
System.Boolean

true if the insert operation was successful; otherwise, false.

OnGotFocus(EventArgs)

Handles the System.Windows.Forms.Control.GotFocus event by transferring focus to the internal text box element and animating the embedded label. This method ensures proper focus management and visual feedback when the control receives focus.

Declaration
protected override void OnGotFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs containing the event data.
Overrides

OnKeyPress(KeyPressEventArgs)

Handles key press events by delegating to the base implementation and internal behavior processing. This method processes character input for the text box control.

Declaration
protected override void OnKeyPress(KeyPressEventArgs e)
Parameters
System.Windows.Forms.KeyPressEventArgs e

A System.Windows.Forms.KeyPressEventArgs containing the event data.
Overrides

OnLoad(Size)

Handles the load event by setting up the embedded label position based on the desired size. This method ensures proper layout initialization when the control is loaded.

Declaration
protected override void OnLoad(Size desiredSize)
Parameters
System.Drawing.Size desiredSize

The desired size for the control layout.
Overrides

OnLostFocus(EventArgs)

Handles the System.Windows.Forms.Control.LostFocus event by removing focus from the internal text box element and animating the embedded label. This method ensures proper focus cleanup and visual feedback when the control loses focus.

Declaration
protected override void OnLostFocus(EventArgs e)
Parameters
System.EventArgs e

An System.EventArgs containing the event data.
Overrides

OnTextChanging(TextChangingEventArgs)

Raises the TextChanging event when text is about to change. This method provides an opportunity for derived classes to handle text changes before they occur.

Declaration
protected virtual void OnTextChanging(TextChangingEventArgs e)
Parameters
TextChangingEventArgs e

The TextChangingEventArgs instance containing the event data.

Paste()

Replaces the currently selected text with the contents of the clipboard. If no text is selected, the clipboard content is inserted at the current cursor position.

Declaration
public bool Paste()
Returns
System.Boolean

true if the paste operation was successful; otherwise, false.

ProcessAutoSizeChanged(Boolean)

Processes changes to the System.Windows.Forms.Control.AutoSize property and adjusts the control's stretch behavior. When AutoSize is disabled, the control can stretch vertically; when enabled, it maintains fixed height based on content.

Declaration
protected override void ProcessAutoSizeChanged(bool value)
Parameters
System.Boolean value

The new value of the AutoSize property.
Overrides

ProcessDialogChar(Char)

Processes dialog characters for the text box control, handling special key combinations. This method manages Alt and Control key combinations while allowing normal character processing for text input.

Declaration
protected override bool ProcessDialogChar(char charCode)
Parameters
System.Char charCode

The character code to process.
Returns
System.Boolean

true if the character was processed by this control; otherwise, false.

ProcessMnemonic(Char)

Processes mnemonic characters for accessibility support. This method handles mnemonic key combinations but returns false as text boxes typically don't support mnemonics.

Declaration
protected override bool ProcessMnemonic(char charCode)
Parameters
System.Char charCode

The mnemonic character to process.
Returns
System.Boolean

false, as text boxes do not typically process mnemonic characters.
Overrides

ResetBackColorThemeOverrides()

Resets theme overrides for the System.Windows.Forms.Control.BackColor property on the text box element and its child elements. This method removes custom background color theming and restores default theme values.

Declaration
protected override void ResetBackColorThemeOverrides()
Overrides

ResetForeColorThemeOverrides()

Resets theme overrides for the System.Windows.Forms.Control.ForeColor property on the text box element. This method removes custom foreground color theming and restores default theme values.

Declaration
protected override void ResetForeColorThemeOverrides()
Overrides

ScrollToCaret()

Scrolls the text box content to ensure the current caret position is visible. This method brings the cursor into view when it might be outside the visible area.

Declaration
public void ScrollToCaret()

Select(Int32, Int32)

Selects a range of text within the text box starting at the specified position. This method sets both the SelectionStart and SelectionLength properties.

Declaration
public void Select(int start, int length)
Parameters
System.Int32 start

The zero-based starting position of the text selection.
System.Int32 length

The number of characters to select from the starting position.

SelectAll()

Selects all text content in the text box. This method sets the selection to include the entire Text property content.

Declaration
public void SelectAll()

SetBackColorThemeOverrides()

Sets theme overrides for the System.Windows.Forms.Control.BackColor property on the text box element and its child elements. This method applies the control's background color to all visual states of the internal text box components.

Declaration
protected override void SetBackColorThemeOverrides()
Overrides

SetForeColorThemeOverrides()

Sets theme overrides for the System.Windows.Forms.Control.ForeColor property on the text box element. This method applies the control's foreground color to all visual states of the internal text box component.

Declaration
protected override void SetForeColorThemeOverrides()
Overrides

Events

ContextMenuOpening

Occurs when the context menu is about to be displayed, allowing customization of menu items. This event provides an opportunity to modify or replace the context menu before it appears to the user.

Declaration
public event TreeBoxContextMenuOpeningEventHandler ContextMenuOpening
Event Type
TreeBoxContextMenuOpeningEventHandler

CreateTextBlock

Occurs when a new text block instance is being created. This event allows customization of ITextBlock creation for advanced text rendering scenarios.

Declaration
public event CreateTextBlockEventHandler CreateTextBlock
Event Type
CreateTextBlockEventHandler

IMECompositionEnded

Occurs when the Input Method Editor (IME) completes text composition for international text input. This event is fired when users finish entering text using an IME and the composition process is complete.

Declaration
public event EventHandler IMECompositionEnded
Event Type
System.EventHandler

IMECompositionResult

Occurs when the Input Method Editor (IME) produces composition results during text input. This event is fired when IME has intermediate or final results ready, which may occur before composition ends for languages like Korean.

Declaration
public event EventHandler<IMECompositionResultEventArgs> IMECompositionResult
Event Type
System.EventHandler<IMECompositionResultEventArgs>

IMECompositionStarted

Occurs when the Input Method Editor (IME) starts text composition for international text input. This event is fired when users begin entering text using an IME for languages such as Chinese, Japanese, or Korean.

Declaration
public event EventHandler IMECompositionStarted
Event Type
System.EventHandler

SelectionChanged

Occurs after the text selection has changed. This event is raised whenever the user or code changes the selected text range within the control.

Declaration
public event SelectionChangedEventHandler SelectionChanged
Event Type
SelectionChangedEventHandler

SelectionChanging

Occurs when the text selection is about to change, allowing the change to be canceled. This event provides an opportunity to prevent selection changes by setting the Cancel property in the event arguments.

Declaration
public event SelectionChangingEventHandler SelectionChanging
Event Type
SelectionChangingEventHandler

TextBlockFormatting

Occurs when text blocks are being formatted, allowing custom styling of text portions. This event provides access to individual text blocks for applying custom formatting such as fonts, colors, or styles.

Declaration
public event TextBlockFormattingEventHandler TextBlockFormatting
Event Type
TextBlockFormattingEventHandler

TextChanging

Occurs when the text content is about to change, providing an opportunity to cancel the change. This event allows validation or modification of text before it is applied to the control.

Declaration
public event TextChangingEventHandler TextChanging
Event Type
TextChangingEventHandler

Extension Methods