Class RadChatElement

Represents a chat element that provides comprehensive chat functionality including message display, user input handling, suggested actions management, overlay features, and extensive customization options for chat user interfaces.

Inheritance
System.Object
DisposableObject
RadObject
RadElement
VisualElement
RadComponentElement
RadItem
UIItemBase
LightVisualElement
RadChatElement
RadPdfChatElement
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.ReferenceEquals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

public class RadChatElement : LightVisualElement, INotifyPropertyChanged, ICustomTypeDescriptor, ISupportSystemSkin, IComponent, IDisposable, IBindableComponent, ISupportDrag, ISupportDrop, IShortcutProvider, IStylableElement, IStylableNode, IPrimitiveElement, IShapedElement, IFillElement, IBorderElement, IBoxStyle, IBoxElement, IDrawFillElement, IImageElement, ITextPrimitive, ITextProvider

Constructors

RadChatElement()

Initializes a new instance of the RadChatElement class with default settings and event wire-up for chat functionality.

Declaration
public RadChatElement()

Properties

Author

Gets or sets the current author that represents the primary user of the chat interface, used for message attribution, alignment, styling, and automatic message creation when AutoAddUserMessages is enabled.

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

See Also

AutoAddUserMessages

Gets or sets a value indicating whether messages typed by the user in the input text box will automatically be added as ChatTextMessage instances to the chat conversation.

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

See Also

AvatarSize

Gets or sets the size of the avatar images displayed next to messages in the chat interface, controlling the visual dimensions of user profile pictures.

Declaration
public SizeF AvatarSize { get; set; }
Property Value
System.Drawing.SizeF

ChatFactory

Gets or sets the chat factory instance used for creating chat-related data items and elements, providing extensibility for custom chat component creation.

Declaration
public ChatFactory ChatFactory { get; set; }
Property Value
ChatFactory

InputTextBox

Gets the input text box element where users type their messages, providing text entry capabilities with support for keyboard shortcuts and clipboard operations.

Declaration
public RadTextBoxElement InputTextBox { get; }
Property Value
RadTextBoxElement

IsOverlayShown

Gets a value indicating whether an overlay is currently displayed, covering the entire chat interface for modal interactions.

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

IsPopupOverlayShown

Gets a value indicating whether a popup overlay is currently displayed, appearing above the chat interface without completely blocking the conversation view.

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

MessagesViewElement

Gets the messages view element that contains, displays, and manages all chat messages with scrolling capabilities and message virtualization support.

Declaration
public ChatMessagesViewElement MessagesViewElement { get; }
Property Value
ChatMessagesViewElement

OverlayElement

Gets the overlay element used for displaying modal content that covers the entire chat interface for important user interactions and confirmations.

Declaration
public LightVisualElement OverlayElement { get; }
Property Value
LightVisualElement

OverlayPopupElement

Gets the overlay popup element used for displaying popup-style content that appears above the chat interface without completely blocking the underlying conversation.

Declaration
public LightVisualElement OverlayPopupElement { get; }
Property Value
LightVisualElement

SendButtonElement

Gets the send button element that enables users to submit their typed messages to the chat conversation with visual feedback and interaction support.

Declaration
public ChatSendButtonElement SendButtonElement { get; }
Property Value
ChatSendButtonElement

ShowAvatars

Gets or sets a value indicating whether avatar images will be displayed in the chat window next to messages, providing visual identification of message authors.

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

ShowMessagesOnOneSide

Gets or sets a value indicating whether messages will be displayed aligned to only one side of the chat window or distributed on both sides based on the message author, affecting the overall conversation layout.

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

ShowToolbarButtonElement

Gets the show toolbar button element that provides toggle functionality for the chat toolbar visibility, allowing users to access extended features on demand.

Declaration
public ChatShowToolbarElement ShowToolbarButtonElement { get; }
Property Value
ChatShowToolbarElement

SuggestedActionsElement

Gets the suggested actions element that displays and manages quick action buttons for streamlined user interactions and response shortcuts.

Declaration
public ChatSuggestedActionsElement SuggestedActionsElement { get; }
Property Value
ChatSuggestedActionsElement

TimeSeparatorInterval

Gets or sets the time interval between messages that will trigger the automatic addition of a time separator element to visually group messages by time periods in the conversation.

Declaration
public TimeSpan TimeSeparatorInterval { get; set; }
Property Value
System.TimeSpan

ToolbarElement

Gets the toolbar element that contains action buttons, controls, and extended functionality options for enhanced chat user interactions.

Declaration
public ChatToolbarElement ToolbarElement { get; }
Property Value
ChatToolbarElement

Methods

AddMessage(ChatMessage)

Adds a new message to the chat conversation, supporting various message types and automatically handling scrolling, suggested actions, and overlay display based on the message type.

Declaration
public virtual void AddMessage(ChatMessage message)
Parameters
ChatMessage message

The ChatMessage to be displayed in the chat conversation. Supported types include ChatTextMessage, ChatSuggestedActionsMessage, ChatMediaMessage, ChatCardMessage, and ChatOverlayMessage.

CreateChildElements()

Creates the child elements that make up the chat interface, including the stack layout, messages view, input controls, toolbar, and overlay elements.

Declaration
protected override void CreateChildElements()
Overrides

CreateInputTextBox()

Creates and configures the input text box element where users type their messages, complete with localized placeholder text and proper sizing.

Declaration
protected virtual RadTextBoxElement CreateInputTextBox()
Returns
RadTextBoxElement

A configured RadTextBoxElement specialized for chat input with appropriate null text and sizing properties.

CreateMessagesListView()

Creates and configures the messages view element that contains and displays all chat messages with automatic sizing capabilities.

Declaration
protected virtual ChatMessagesViewElement CreateMessagesListView()
Returns
ChatMessagesViewElement

A configured ChatMessagesViewElement with proper auto-sizing and reference to the parent chat element.

CreateOverlayPopupElement()

Creates and configures the overlay popup element that displays popup-style overlays for modal interactions and user prompts.

Declaration
protected virtual OverlayPopupElement CreateOverlayPopupElement()
Returns
OverlayPopupElement

A configured OverlayPopupElement with initial collapsed visibility.

CreateSendButton()

Creates and configures the send button element that allows users to submit their typed messages to the chat conversation.

Declaration
protected virtual ChatSendButtonElement CreateSendButton()
Returns
ChatSendButtonElement

A configured ChatSendButtonElement with appropriate padding settings.

CreateShowToolbarButton()

Creates and configures the show toolbar button element that toggles the visibility of the chat toolbar containing action buttons and controls.

Declaration
protected virtual ChatShowToolbarElement CreateShowToolbarButton()
Returns
ChatShowToolbarElement

A configured ChatShowToolbarElement with appropriate font settings and ellipsis text.

CreateStackLayoutElement()

Creates and configures the main stack layout element that organizes all chat components vertically with proper sizing and orientation settings.

Declaration
protected virtual StackLayoutElement CreateStackLayoutElement()
Returns
StackLayoutElement

A configured StackLayoutElement with vertical orientation and appropriate stretching properties.

CreateSuggestedActionsElement()

Creates and configures the suggested actions element that displays quick action buttons for user interaction and response shortcuts.

Declaration
protected virtual ChatSuggestedActionsElement CreateSuggestedActionsElement()
Returns
ChatSuggestedActionsElement

A configured ChatSuggestedActionsElement with proper sizing, visibility settings, and reference to the parent chat element.

CreateToolbarElement()

Creates and configures the toolbar element that contains action buttons and controls for extended chat functionality and user interactions.

Declaration
protected virtual ChatToolbarElement CreateToolbarElement()
Returns
ChatToolbarElement

A configured ChatToolbarElement with proper sizing and reference to the parent chat element.

CreateTypingIndicatorElement()

Creates and configures the typing indicator element that displays visual feedback when users or other participants are actively typing messages.

Declaration
protected virtual LightVisualElement CreateTypingIndicatorElement()
Returns
LightVisualElement

A configured LightVisualElement with typing indicator image, proper alignment settings, and initial collapsed visibility.

DisposeManagedResources()

Disposes managed resources and unwires event handlers to ensure proper cleanup when the chat element is destroyed.

Declaration
protected override void DisposeManagedResources()
Overrides

HideOverlay()

Hides any overlays that are currently displayed by the chat control, restoring normal chat functionality and returning focus to the input text box.

Declaration
public virtual void HideOverlay()

HideTypingIndicator()

Hides the typing indicator, removing the visual feedback about users typing and clearing any associated text or animation.

Declaration
public virtual void HideTypingIndicator()

OnCardActionClicked(Object, CardActionEventArgs)

Raises the CardActionClicked event when a user clicks on a card action, providing event arguments with the action details and source card information.

Declaration
protected virtual void OnCardActionClicked(object sender, CardActionEventArgs e)
Parameters
System.Object sender

The card element that triggered the event.
CardActionEventArgs e

A CardActionEventArgs that contains the event data including the card action that was clicked.

OnCopy(CopyEventArgs)

Raises the Copy event using the specified event data.

Declaration
protected virtual void OnCopy(CopyEventArgs e)
Parameters
CopyEventArgs e

The event data containing information about the copy operation.
Remarks

Derived classes can override this method to provide custom handling when a copy operation is initiated or completed.

OnInputTextBoxKeyDown(Object, KeyEventArgs)

Handles key down events in the input text box, processing Enter key submissions and Ctrl+V paste operations for images from the clipboard.

Declaration
protected virtual void OnInputTextBoxKeyDown(object sender, KeyEventArgs e)
Parameters
System.Object sender

The source of the event.
System.Windows.Forms.KeyEventArgs e

A System.Windows.Forms.KeyEventArgs that contains the event data including key information.

OnItemFormatting(ChatItemElementEventArgs)

Raises the ItemFormatting event when a chat item element is being prepared for display, allowing custom formatting and styling of message elements.

Declaration
protected virtual void OnItemFormatting(ChatItemElementEventArgs e)
Parameters
ChatItemElementEventArgs e

A ChatItemElementEventArgs that contains the event data including the element being formatted and its associated data.

OnPropertyChanged(RadPropertyChangedEventArgs)

Declaration
protected override void OnPropertyChanged(RadPropertyChangedEventArgs e)
Parameters
RadPropertyChangedEventArgs e

Overrides

OnRegenerateResponse(RegenerateResponseEventArgs)

Raises the RegenerateResponse event using the specified event data.

Declaration
protected virtual void OnRegenerateResponse(RegenerateResponseEventArgs e)
Parameters
RegenerateResponseEventArgs e

The event data associated with the RegenerateResponse event.
Remarks

Override this method in a derived class to provide custom handling when the RegenerateResponse event is raised.

OnSendButtonElementClick(Object, EventArgs)

Handles click events on the send button element, submitting user messages when the input text box contains non-whitespace content.

Declaration
protected virtual void OnSendButtonElementClick(object sender, EventArgs e)
Parameters
System.Object sender

The source of the event.
System.EventArgs e

An System.EventArgs that contains the event data.

OnSendMessage(SendMessageEventArgs)

Raises the SendMessage event when a user action triggers message sending, providing event arguments with the message details.

Declaration
protected virtual void OnSendMessage(SendMessageEventArgs e)
Parameters
SendMessageEventArgs e

A SendMessageEventArgs that contains the event data including the message being sent.

OnShowToolbarButtonElementClick(Object, EventArgs)

Handles click events on the show toolbar button element, toggling the visibility of the chat toolbar to provide access to extended functionality.

Declaration
protected virtual void OnShowToolbarButtonElementClick(object sender, EventArgs e)
Parameters
System.Object sender

The source of the event.
System.EventArgs e

An System.EventArgs that contains the event data.

OnSuggestedActionClicked(SuggestedActionEventArgs)

Raises the SuggestedActionClicked event when a user clicks on a suggested action, providing event arguments with the action details.

Declaration
protected virtual void OnSuggestedActionClicked(SuggestedActionEventArgs e)
Parameters
SuggestedActionEventArgs e

A SuggestedActionEventArgs that contains the event data including the suggested action that was clicked.

OnTimeSeparatorAdding(TimeSeparatorEventArgs)

Raises the TimeSeparatorAdding event when a message is being added, allowing custom logic to determine time separator insertion.

Declaration
protected virtual void OnTimeSeparatorAdding(TimeSeparatorEventArgs e)
Parameters
TimeSeparatorEventArgs e

A TimeSeparatorEventArgs that contains the event data including timing information and separator insertion control.

OnToolbarActionClick(ToolbarActionEventArgs)

Raises the ToolbarActionClicked event when a user clicks on a toolbar action, providing event arguments with the action details.

Declaration
protected virtual void OnToolbarActionClick(ToolbarActionEventArgs e)
Parameters
ToolbarActionEventArgs e

A ToolbarActionEventArgs that contains the event data including the toolbar action that was clicked.

OnUserVoted(UserVotedEventArgs)

Raises the UserVoted event using the specified event data.

Declaration
protected virtual void OnUserVoted(UserVotedEventArgs e)
Parameters
UserVotedEventArgs e

The event data containing information about the user vote.
Remarks

Derived classes can override this method to provide custom handling when a user vote occurs. This method invokes the UserVoted event if there are any subscribers.

OnVisualItemCreating(VisualItemCreatingEventArgs)

Raises the VisualItemCreating event to allow customization or handling when a visual item is being created.

Declaration
protected virtual void OnVisualItemCreating(VisualItemCreatingEventArgs e)
Parameters
VisualItemCreatingEventArgs e

An object that contains the event data for the visual item creation process.
Remarks

Derived classes can override this method to provide custom logic when a visual item is being created. This method is typically called before the visual item is added to the control.

PostPaintChildren(IGraphics, Rectangle, Single, SizeF)

Performs post-paint operations for child elements, including custom border painting to enhance the visual appearance of the chat interface.

Declaration
protected override void PostPaintChildren(IGraphics graphics, Rectangle clipRectangle, float angle, SizeF scale)
Parameters
IGraphics graphics

The IGraphics object used for painting operations.
System.Drawing.Rectangle clipRectangle

The clipping rectangle that defines the visible area for painting.
System.Single angle

The rotation angle for the painting operation.
System.Drawing.SizeF scale

The scaling factor for the painting operation.
Overrides

ProcessMouseWheel(MouseEventArgs)

Handles mouse wheel events to provide smooth scrolling functionality within the chat messages area, automatically calculating and applying appropriate scroll values.

Declaration
public virtual void ProcessMouseWheel(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

A System.Windows.Forms.MouseEventArgs that contains the mouse wheel event data including delta values for scroll calculations.

ShowOverlay(ChatOverlayMessage)

Displays the specified overlay message in the chat interface, supporting both modal overlays that block the input and popup overlays that appear above the conversation.

Declaration
public virtual void ShowOverlay(ChatOverlayMessage message)
Parameters
ChatOverlayMessage message

The ChatOverlayMessage containing the overlay information, display configuration, and content to be shown to the user.

ShowTypingIndicator(Author[])

Displays a typing indicator for the specified authors, providing visual feedback to users about who is currently composing messages in the chat conversation.

Declaration
public virtual void ShowTypingIndicator(params Author[] authors)
Parameters
Author[] authors

The authors who are currently typing messages. If null or empty, displays a generic typing animation without author names.

SubmitUserMessage()

Submits the current user message from the input text box, handling validation, message creation, and event firing based on the auto-add user messages setting.

Declaration
protected virtual void SubmitUserMessage()

UnwireEvents()

Unwires event handlers to prevent memory leaks and ensure proper cleanup when the chat element is disposed or destroyed.

Declaration
protected virtual void UnwireEvents()

WireEvents()

Wires up event handlers for chat functionality including input text box interactions, button clicks, and localization provider changes.

Declaration
protected virtual void WireEvents()

Events

CardActionClicked

Occurs when the user clicks on a card action element within a ChatCardMessage, enabling interactive card-based interfaces and rich content interactions.

Declaration
public event CardActionEventHandler CardActionClicked
Event Type
CardActionEventHandler

Copy

Occurs when a copy operation is initiated or completed.

Declaration
public event EventHandler<CopyEventArgs> Copy
Event Type
System.EventHandler<CopyEventArgs>

Remarks

Subscribers can use this event to respond to copy actions, such as updating the user interface or logging the operation. The event provides a CopyEventArgs instance containing details about the copy event.

ItemFormatting

Occurs when the data item of a visual element is changed and the element is prepared for visualization, allowing customization of message appearance, styling, and layout properties.

Declaration
public event ChatItemElementEventHandler ItemFormatting
Event Type
ChatItemElementEventHandler

RegenerateResponse

Occurs when a response needs to be regenerated, allowing subscribers to handle or modify the regeneration process.

Declaration
public event EventHandler<RegenerateResponseEventArgs> RegenerateResponse
Event Type
System.EventHandler<RegenerateResponseEventArgs>

Remarks

Subscribers can use this event to perform custom actions or update the UI when a response regeneration is triggered. The event provides a RegenerateResponseEventArgs instance containing relevant event data.

SendMessage

Occurs when the user performs a message-sending action such as pressing the Enter key, clicking the Send message button, clicking on a suggested action, clicking on a card action, or confirming an overlay interaction.

Declaration
public event SendMessageEventHandler SendMessage
Event Type
SendMessageEventHandler

SuggestedActionClicked

Occurs when the user clicks on a suggested action element within a ChatSuggestedActionsMessage, providing quick response options and streamlined user interactions.

Declaration
public event SuggestedActionEventHandler SuggestedActionClicked
Event Type
SuggestedActionEventHandler

TimeSeparatorAdding

Occurs after a new message is added to the chat but before it is displayed, allowing customization of whether a time separator should be inserted before the currently added message based on timing and context.

Declaration
public event TimeSeparatorEventHandler TimeSeparatorAdding
Event Type
TimeSeparatorEventHandler

ToolbarActionClicked

Occurs when the user clicks on a toolbar action element, providing access to chat-level functionality and administrative operations.

Declaration
public event ToolbarActionEventHandler ToolbarActionClicked
Event Type
ToolbarActionEventHandler

UserVoted

Occurs when a user submits a vote.

Declaration
public event EventHandler<UserVotedEventArgs> UserVoted
Event Type
System.EventHandler<UserVotedEventArgs>

Remarks

Subscribe to this event to be notified whenever a user completes a voting action. The event provides details about the user and the vote through the UserVotedEventArgs parameter.

VisualItemCreating

Occurs when a new visual item is being created, allowing customization of its initialization or appearance.

Declaration
public event EventHandler<VisualItemCreatingEventArgs> VisualItemCreating
Event Type
System.EventHandler<VisualItemCreatingEventArgs>

Remarks

Handle this event to modify or configure visual items before they are added to the visual tree. This event is typically raised during the rendering or data binding process, enabling developers to set properties or attach behaviors to visual elements as they are instantiated.

Extension Methods