ClassRadTextBoxControlElement
Represents an independent text box element that provides comprehensive text editing capabilities including auto-completion, scrolling, selection management, and input handling. This element serves as the core implementation for text box controls and extends ScrollViewElement<T> with specialized text editing functionality.
Definition
Namespace:Telerik.WinControls.UI
Assembly:Telerik.WinControls.UI.dll
Syntax:
public class RadTextBoxControlElement : ScrollViewElement<TextBoxViewElement>, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IBindableComponent, IComponent, IDisposable, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProviderInheritance: objectDisposableObjectRadObjectRadElementVisualElementRadComponentElementRadItemUIItemBaseLightVisualElementScrollViewElement<TextBoxViewElement>RadTextBoxControlElement
Derived Classes:
Implements:
Inherited Members
Constructors
RadTextBoxControlElement()
Initializes a new instance of the RadTextBoxControlElement class.
Declaration
public RadTextBoxControlElement()Properties
AcceptsReturn
Gets or sets a value indicating whether pressing ENTER in a multiline TextBox element creates a new line of text in the element or activates the default button for the form.
Declaration
public bool AcceptsReturn { get; set; }Property Value
true if ENTER key creates a new line; otherwise, false to activate the default button.
AcceptsTab
Gets or sets a value indicating whether pressing the TAB key in a multiline text box element types a TAB character in the element instead of moving the focus to the next element in the tab order.
Declaration
public bool AcceptsTab { get; set; }Property Value
true if TAB key inserts a tab character; otherwise, false to move focus to next control.
AutoCompleteDataSource
Gets or sets a value specifying the source of complete items used for automatic completion.
Declaration
public object AutoCompleteDataSource { get; set; }Property Value
The data source providing auto-completion suggestions, or null if using the AutoCompleteItems collection.
AutoCompleteDisplayMember
Gets or sets the auto complete display member.
Declaration
public string AutoCompleteDisplayMember { get; set; }Property Value
The property name used to display text for auto-completion items.
AutoCompleteDropDown
Gets the auto complete drop down.
Declaration
public RadPopupControlBase AutoCompleteDropDown { get; }Property Value
The popup control that hosts the auto-completion dropdown list.
AutoCompleteItems
Gets a value specifying the complete items used for automatic completion.
Declaration
public RadListDataItemCollection AutoCompleteItems { get; }Property Value
The collection of items used for auto-completion when no data source is specified.
AutoCompleteMode
Gets or sets an option that controls how automatic completion works for the TextBox.
Declaration
public AutoCompleteMode AutoCompleteMode { get; set; }Property Value
The auto-completion mode that determines how suggestions are presented to the user.
CanPerformAutoComplete
Gets a value indicating whether this text box can perform auto complete operation.
Declaration
protected virtual bool CanPerformAutoComplete { get; }Property Value
true if auto-completion is enabled and the text box is single-line; otherwise, false.
Caret
Gets the associated caret.
Declaration
public TextBoxControlCaret Caret { get; }Property Value
The text cursor element that indicates the insertion point.
CaretIndex
Gets or sets the caret position.
Declaration
public int CaretIndex { get; set; }Property Value
The zero-based index of the caret position within the text.
CharacterCasing
Gets or sets whether the TextBox element modifies the case of characters as they are typed.
Declaration
public CharacterCasing CharacterCasing { get; set; }Property Value
The character casing mode applied to typed text.
ClearButton
Gets the clear button.
Declaration
public LightVisualButtonElement ClearButton { get; }Property Value
The button element that allows users to quickly clear all text.
ContextMenu
Gets or sets the associated context menu.
Declaration
public RadContextMenu ContextMenu { get; set; }Property Value
The context menu displayed on right-click, or null if no context menu is assigned.
DropDownMaxSize
Gets or sets the maximum size of the auto-complete dropdown.
DropDownMinSize
Gets or sets the minimum size of the auto-complete dropdown.
EmbeddedLabel
Gets an instance of the corresponding embedded label.
Declaration
public LightVisualElement EmbeddedLabel { get; }Property Value
The embedded label element displayed within the text box.
EmbeddedLabelAnimationSpeed
Gets or set the animation speed of the embedded label. The speed is an integer between 1(off) and 10(slowest) with default value of 8.
Declaration
public int EmbeddedLabelAnimationSpeed { get; set; }Property Value
The animation speed from 1 (disabled) to 10 (slowest), with 8 as the default.
EmbeddedLabelBorderOffset
Gets or set the offset of the embedded label from the bottom border, when the label is down.
Declaration
public float EmbeddedLabelBorderOffset { get; set; }Property Value
The offset distance in pixels from the bottom border when the label is in its lowered position.
EmbeddedLabelText
Gets or sets the text of the embedded label.
Declaration
public string EmbeddedLabelText { get; set; }Property Value
The text content displayed in the embedded label.
HideSelection
Gets or sets a value indicating whether the selected text in the text box control remains highlighted when the element loses focus.
Declaration
public bool HideSelection { get; set; }Property Value
true if selection should be hidden when unfocused; otherwise, false to keep selection visible.
HorizontalScrollBarState
Gets or sets when the horizontal scroll bar should appear in a multiline TextBox element.
Declaration
public ScrollState HorizontalScrollBarState { get; set; }Property Value
The visibility state of the horizontal scroll bar.
InputHandler
Represents the associated keyboard and mouse input handler.
Declaration
public ITextBoxInputHandler InputHandler { get; set; }Property Value
The input handler responsible for processing user interactions.
IsAutoCompleteDropDownOpen
Gets a value indicating whether this auto-complete drop down is open.
Declaration
[Browsable(false)]
public bool IsAutoCompleteDropDownOpen { get; }Property Value
true if the auto-complete dropdown is currently displayed; otherwise, false.
IsReadOnly
Gets or sets a value indicating whether text in the text box is read-only.
Declaration
public bool IsReadOnly { get; set; }Property Value
true if the text box is read-only and cannot be edited; otherwise, false.
IsReadOnlyCaretVisible
Gets or sets a value indicating whether the caret is visible in read only mode.
Declaration
public bool IsReadOnlyCaretVisible { get; set; }Property Value
true if the caret should be visible even when read-only; otherwise, false.
Lines
Gets or sets the lines of text in a text box element.
Declaration
public string[] Lines { get; set; }Property Value
string[]
An array of strings representing each line of text in the text box.
ListElement
Gets the auto-complete list element.
Declaration
public RadTextBoxListElement ListElement { get; }Property Value
The list element that displays auto-completion suggestions.
MaxDropDownItemCount
Gets or sets the max count of visible items in auto-complete drop down.
Declaration
public int MaxDropDownItemCount { get; set; }Property Value
The maximum number of items displayed simultaneously in the dropdown before scrolling is required.
MaxLength
Gets or sets the maximum number of characters the user can type or paste into the text box element.
Multiline
Gets or sets a value indicating whether this is a multiline text box.
Declaration
public bool Multiline { get; set; }Property Value
true if the text box accepts multiple lines of text; otherwise, false for single-line input.
Navigator
Gets or sets the navigator of the text position.
Declaration
public ITextBoxNavigator Navigator { get; set; }Property Value
The navigator responsible for text positioning and selection management.
NullText
Gets or sets the prompt text that is displayed when the text box contains no text.
Declaration
public string NullText { get; set; }Property Value
The text to display when the text box is empty.
NullTextColor
Gets or sets the color of the null text.
Declaration
public Color NullTextColor { get; set; }Property Value
The color used to display the null text.
NullTextViewElement
Gets the view element of the null text.
Declaration
public TextBoxWrapPanel NullTextViewElement { get; }Property Value
The panel element that displays placeholder text when the text box is empty.
PasswordChar
Gets or sets the character used to mask characters of a password in a single-line text box.
Declaration
public virtual char PasswordChar { get; set; }Property Value
The character used to mask password input, or '\0' to display actual characters.
RepositionEmbeddedLabel
Gets or set whether to reposition the embedded label, when text box is empty.
Declaration
public bool RepositionEmbeddedLabel { get; set; }Property Value
true if the embedded label should move when the text box becomes empty; otherwise, false.
SelectedText
Gets or sets a value indicating the currently selected text in the element.
Declaration
public string SelectedText { get; set; }Property Value
The text currently selected by the user, or an empty string if no text is selected.
SelectionColor
Gets or sets the color of the selection.
Declaration
public Color SelectionColor { get; set; }Property Value
The background color used to highlight selected text.
SelectionLength
Gets or sets the number of characters selected in the text box.
Declaration
public int SelectionLength { get; set; }Property Value
The number of characters selected, or 0 if no text is selected.
SelectionOpacity
Gets or sets the selection opacity.
Declaration
public int SelectionOpacity { get; set; }Property Value
The opacity level of the selection highlight (0-255).
SelectionStart
Gets or sets the starting point of text selected in the text box.
Declaration
public int SelectionStart { get; set; }Property Value
The zero-based index of the first character in the current text selection.
ShowClearButton
Gets or sets a value indicating whether the clear button is shown.
Declaration
public bool ShowClearButton { get; set; }Property Value
true if the clear button should be displayed; otherwise, false.
ShowEmbeddedLabel
Gets or sets the visibility of the embedded label. It is recommended to set AutoSize to true, when using the embedded label.
Declaration
public bool ShowEmbeddedLabel { get; set; }Property Value
true if the embedded label should be visible; otherwise, false.
ShowNullText
Gets or sets a value indicating whether the null text will be shown when the control is focused and the text is empty.
Declaration
[Browsable(false)]
public bool ShowNullText { get; set; }Property Value
true if null text should be displayed when focused and empty; otherwise, false.
Text
Gets or sets the current text in the text box element.
Declaration
public override string Text { get; set; }Property Value
Overrides
TextAlign
Gets or sets how the text is horizontally aligned in the element.
Declaration
public HorizontalAlignment TextAlign { get; set; }Property Value
The horizontal alignment of text within the text box.
TextLength
Gets the length of text in the element.
Declaration
public int TextLength { get; }Property Value
The total number of characters in the text box.
UseSystemPasswordChar
Gets or sets a value indicating whether the text in view should appear as the default password character.
Declaration
public virtual bool UseSystemPasswordChar { get; set; }Property Value
true to use the system password character; otherwise, false to display actual characters.
VerticalScrollBarState
Gets or sets when the vertical scroll bar should appear in a multiline TextBox element.
Declaration
public ScrollState VerticalScrollBarState { get; set; }Property Value
The visibility state of the vertical scroll bar.
Methods
AppendText(string)
Appends text to the current text of a text box.
Declaration
public void AppendText(string text)Parameters
text
The text to append.
AppendText(string, bool)
Appends text to the current text of a text box and optionally selects it.
ArrangeOverride(SizeF)
Arranges the content and child elements within the final allocated space, positioning text, images, and child elements.
ArrangeViewElement(RectangleF)
Arranges the view element.
Declaration
protected override void ArrangeViewElement(RectangleF viewElementRect)Parameters
viewElementRect
The view element rect.
Overrides
CanInsertText(string)
Determines whether the text can be inserted
ClampOffset(int)
Clamps the offset to valid text position bounds.
CloseDropDown()
Closes the auto-complete drop down.
Declaration
public void CloseDropDown()CloseDropDown(RadPopupCloseReason)
Closes the drop down.
Declaration
public virtual void CloseDropDown(RadPopupCloseReason reason)Parameters
reason
The reason for closing the dropdown.
Copy()
Copies the current selection in the text box to the Clipboard.
Declaration
public virtual bool Copy()Returns
true if text was copied to the clipboard; otherwise, false.
CreateAutoCompleteDropDown()
Creates the auto-complete drop down.
Declaration
protected virtual RadPopupControlBase CreateAutoCompleteDropDown()Returns
A new instance of RadPopupControlBase for hosting the auto-completion dropdown.
CreateCaret()
Creates the caret of the text box element.
Declaration
protected virtual TextBoxControlCaret CreateCaret()Returns
A new instance of TextBoxControlCaret for text position indication.
CreateChildElements()
Creates the child elements that comprise the text box control, including the view element, scrollbars, caret, and supporting components.
Declaration
protected override void CreateChildElements()Overrides
CreateClearButton()
Creates the clear button element that allows users to quickly clear all text from the text box.
Declaration
protected virtual LightVisualButtonElement CreateClearButton()Returns
A new LightVisualButtonElement configured as a clear button.
CreateEmbeddedLabel()
Creates the embedded label element that can be displayed within the text box control.
Declaration
protected virtual LightVisualElement CreateEmbeddedLabel()Returns
A new LightVisualElement configured as an embedded label.
CreateListElement()
Creates the auto-complete list element.
Declaration
protected virtual RadTextBoxListElement CreateListElement()Returns
A new instance of RadTextBoxListElement for displaying auto-completion suggestions.
CreateNullTextViewElement()
Creates an instance of TextBoxWrapPanel used to display placeholder text when the text box is empty.
Declaration
protected virtual TextBoxWrapPanel CreateNullTextViewElement()Returns
A new TextBoxWrapPanel instance configured for null text display.
Cut()
Moves the current selection in the text box to the Clipboard.
Declaration
public virtual bool Cut()Returns
true if the operation was successful; otherwise, false.
Delete()
Deletes the selected text or character at the current position.
Declaration
public bool Delete()Returns
true if text was successfully deleted; otherwise, false.
Delete(bool)
Deletes the selected text or character at the current position.
Delete(bool, bool)
Deletes the selected text or character at the current position.
Declaration
public virtual bool Delete(bool nextCharacter, bool isControlPressed)Parameters
nextCharacter
If set to true, deletes the next character; otherwise, deletes the previous character.
isControlPressed
If set to true and Control modifier key is pressed, deletes to the end of the word.
Returns
true if text was successfully deleted; otherwise, false.
DeselectAll()
Specifies that the value of the SelectionLength property is zero so that no characters are selected in the element.
Declaration
public virtual bool DeselectAll()Returns
true if the selection was successfully cleared; otherwise, false.
DisposeUnmanagedResources()
Disposes of unmanaged resources used by the text box control element.
Declaration
protected override void DisposeUnmanagedResources()Overrides
DpiScaleChanged(SizeF)
Called when the DPI scale factor changes. Updates the scale factor and notifies child elements.
Declaration
public override void DpiScaleChanged(SizeF scaleFactor)Parameters
scaleFactor
The new DPI scale factor.
Overrides
GetAutoCompleteDropDownLocation()
Gets the auto-complete drop down location.
Declaration
protected virtual Point GetAutoCompleteDropDownLocation()Returns
The screen coordinates where the auto-complete dropdown should be positioned.
GetAutoCompleteTextCondition(TextPosition, TextPosition)
Gets the text that is used as filter condition in auto-completion.
Declaration
protected virtual string GetAutoCompleteTextCondition(TextPosition startPosition, TextPosition endPosition)Parameters
startPosition
The start position of the text range.
endPosition
The end position of the text range.
Returns
The text that will be used to filter auto-completion suggestions.
GetDropDownSize()
Gets the size of the auto-complete drop down.
Declaration
protected virtual Size GetDropDownSize()Returns
The calculated size for the auto-complete dropdown based on item count and constraints.
GetFirstAutoCompletePosition()
Gets the first position for auto-completion text within the view element.
Declaration
protected virtual TextPosition GetFirstAutoCompletePosition()Returns
The text position representing the start of auto-completion.
GetLastAutoCompletePosition()
Gets the last position for auto-completion text within the view element.
Declaration
protected virtual TextPosition GetLastAutoCompletePosition()Returns
The text position representing the end of auto-completion.
GetLines()
Gets the lines of the text box element.
Declaration
protected virtual string[] GetLines()Returns
string[]
An array of strings representing each line in the text box.
HandleSuggestedTextChanged(SuggestedTextChangedEventArgs)
Handles processing of suggested text changes for auto-completion functionality.
Declaration
protected virtual void HandleSuggestedTextChanged(SuggestedTextChangedEventArgs e)Parameters
e
The suggested text changed event arguments.
InitializeFields()
Initializes the default field values for the text box control element.
Declaration
protected override void InitializeFields()Overrides
Insert(string)
Inserts the text at current position.
IsInputKey(InputKeyEventArgs)
Determines whether the specified key is an input key that should be processed by the text box.
Declaration
protected override bool IsInputKey(InputKeyEventArgs e)Parameters
e
The input key event arguments containing key information.
Returns
true if the key should be processed as input; otherwise, false.
Overrides
IsValidAutoCompletePosition()
Determines whether the current position is valid for the auto-complete operation
Declaration
protected virtual bool IsValidAutoCompletePosition()Returns
true if [is valid auto complete position]; otherwise, false.
MeasureOverride(SizeF)
Measures the desired size of the element by calculating the space needed for content, padding, and borders.
MeasureViewElement(SizeF)
Declaration
protected override void MeasureViewElement(SizeF availableSize)Parameters
availableSize
Overrides
OnAutoCompleteDropDownClosed(RadAutoCompleteDropDownClosedEventArgs)
Called when the auto-complete dropdown is closed.
Declaration
protected virtual void OnAutoCompleteDropDownClosed(RadAutoCompleteDropDownClosedEventArgs e)Parameters
e
RadAutoCompleteDropDownClosedEventArgs
The auto-complete dropdown closed event arguments.
OnBoundsChanged(RadPropertyChangedEventArgs)
Called when the bounds of the element have changed.
Declaration
protected override void OnBoundsChanged(RadPropertyChangedEventArgs e)Parameters
e
The event arguments containing bound change information.
Overrides
OnContextMenuOpening(RadContextMenu)
Called when the context menu is opening.
Declaration
protected bool OnContextMenuOpening(RadContextMenu menu)Parameters
menu
The context menu being opened.
Returns
true if the menu should be displayed; otherwise, false to cancel the operation.
OnContextMenuOpening(TreeBoxContextMenuOpeningEventArgs)
Raises the ContextMenuOpening event.
Declaration
protected virtual void OnContextMenuOpening(TreeBoxContextMenuOpeningEventArgs e)Parameters
e
TreeBoxContextMenuOpeningEventArgs
The TreeBoxContextMenuOpeningEventArgs instance containing the event data.
OnDoubleClick(EventArgs)
Called when the element is double-clicked.
Declaration
protected override void OnDoubleClick(EventArgs e)Parameters
e
The event arguments.
Overrides
OnIMECompositionEnded()
Raises the IMECompositionEnded event when Input Method Editor composition completes.
Declaration
protected virtual void OnIMECompositionEnded()OnIMECompositionResult(string)
Raises the IMECompositionResult event when Input Method Editor produces a result.
Declaration
protected virtual void OnIMECompositionResult(string result)Parameters
result
The composition result text.
OnIMECompositionStarted()
Raises the IMECompositionStarted event when Input Method Editor composition begins.
Declaration
protected virtual void OnIMECompositionStarted()OnKeyDown(KeyEventArgs)
Raises the KeyDown event.
Declaration
protected override void OnKeyDown(KeyEventArgs e)Parameters
e
The key event arguments.
Overrides
OnKeyPress(KeyPressEventArgs)
Raises the KeyPress event.
Declaration
protected override void OnKeyPress(KeyPressEventArgs e)Parameters
e
The key press event arguments.
Overrides
OnKeyUp(KeyEventArgs)
Raises the KeyUp event.
Declaration
protected override void OnKeyUp(KeyEventArgs e)Parameters
e
The key event arguments.
Overrides
OnLoaded()
Called when the element has been loaded and is ready for interaction.
Declaration
protected override void OnLoaded()Overrides
OnMouseDown(MouseEventArgs)
Called when a mouse button is pressed down over the item.
Declaration
protected override void OnMouseDown(MouseEventArgs e)Parameters
e
The mouse event arguments.
Overrides
OnMouseEnter(EventArgs)
Called when the mouse enters the element bounds.
Declaration
protected override void OnMouseEnter(EventArgs e)Parameters
e
The event arguments.
Overrides
OnMouseLeave(EventArgs)
Called when the mouse leaves the element bounds.
Declaration
protected override void OnMouseLeave(EventArgs e)Parameters
e
The event arguments.
Overrides
OnMouseMove(MouseEventArgs)
Called when the mouse moves over the element.
Declaration
protected override void OnMouseMove(MouseEventArgs e)Parameters
e
The mouse event arguments.
Overrides
OnMouseUp(MouseEventArgs)
Called when a mouse button is released over the element.
Declaration
protected override void OnMouseUp(MouseEventArgs e)Parameters
e
The mouse event arguments.
Overrides
OnMouseWheel(MouseEventArgs)
Called when the mouse wheel is scrolled over the element.
Declaration
protected override void OnMouseWheel(MouseEventArgs e)Parameters
e
The mouse event arguments.
Overrides
OnPropertyChanged(RadPropertyChangedEventArgs)
Called when a property of the element has changed.
Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)Parameters
e
The property changed event arguments.
Overrides
OnUnloaded(ComponentThemableElementTree)
Called when the element is being unloaded from the visual tree.
Declaration
protected override void OnUnloaded(ComponentThemableElementTree oldTree)Parameters
oldTree
The component tree from which the element is being removed.
Overrides
PaintText(IGraphics)
Overrides the text painting to prevent default text rendering since text is handled by the view element.
Declaration
protected override void PaintText(IGraphics graphics)Parameters
graphics
The graphics context for painting.
Overrides
Paste()
Replaces the current selection in the text box with the contents of the Clipboard.
Declaration
public virtual bool Paste()Returns
true if text was pasted from the clipboard; otherwise, false.
PerformAutoComplete(EditOperation)
Performs the auto-complete for concrete operation.
Declaration
protected void PerformAutoComplete(EditOperation context)Parameters
context
The context.
PerformAutoCompleteOverride(EditOperation)
Performs the auto complete override.
Declaration
protected virtual void PerformAutoCompleteOverride(EditOperation context)Parameters
context
The context.
Redo()
Redo the last undo action.
Declaration
public virtual bool Redo()Returns
true if an action was successfully redone; otherwise, false.
ScrollToCaret()
Scrolls the contents of the control to the current caret position.
Declaration
public void ScrollToCaret()Select(int, int)
Selects a range of text in the text box.
SelectAll()
Selects all text in the text box element.
Declaration
public void SelectAll()SetLines(string[])
Sets the lines of the text box element.
Declaration
protected virtual void SetLines(string[] value)Parameters
value
string[]
The array of strings to set as text lines.
ShowDropDown(Point)
Shows the drop down.
Declaration
public virtual void ShowDropDown(Point location)Parameters
location
The screen location where the dropdown should appear.
ToggleTextPrimitive(RadProperty)
Toggles the text primitive display (overridden to prevent default text rendering).
Declaration
protected override void ToggleTextPrimitive(RadProperty property)Parameters
property
The property being toggled.
Overrides
Events
ContextMenuOpening
Occurs when the context menu is opening.
Declaration
public event TreeBoxContextMenuOpeningEventHandler ContextMenuOpeningEvent Value
CreateTextBlock
Occurs when an instance of ITextBlock is created.
Declaration
public event CreateTextBlockEventHandler CreateTextBlockEvent Value
IMECompositionEnded
Fired when the Input Method Editor completes the composition.
Declaration
public event EventHandler IMECompositionEndedEvent Value
IMECompositionResult
Fired when the Input Method Editor has a result ready. For languages like Korean this might happen before the composition has ended.
Declaration
public event EventHandler<IMECompositionResultEventArgs> IMECompositionResultEvent Value
EventHandler<IMECompositionResultEventArgs>
IMECompositionStarted
Fired when the Input Method Editor starts the composition.
Declaration
public event EventHandler IMECompositionStartedEvent Value
SelectionChanged
Occurs when text selection is changed.
Declaration
public event SelectionChangedEventHandler SelectionChangedEvent Value
SelectionChanging
Occurs when text selection is changing.
Declaration
public event SelectionChangingEventHandler SelectionChangingEvent Value
TextBlockFormatting
Occurs when text block is formatting.
Declaration
public event TextBlockFormattingEventHandler TextBlockFormattingEvent Value