ChatBox

Namespace: Wisej.Web.Ext.ChatControl

Assembly: Wisej.Web.Ext.ChatControl (4.1.0.0)

• Control
  • ScrollableControl
    • ContainerControl
      • UserControl
        • ChatBox

Provides a control with chat functionality: a scrollable list of message bubbles and an input box with a send button.

C#

public class ChatBox : UserControl

VB.NET

Public Class ChatBox
    Inherits UserControl

Messages are managed through the DataSource collection: adding a Message to it renders the message, removing it removes the rendered control. Messages typed by the user are added automatically when the user presses Enter or clicks the send button. The default event is SentMessage.

Example:

var chatBox = new ChatBox { Dock = DockStyle.Fill };
chatBox.User = new User("1", "Alice");
chatBox.SentMessage += (s, e) => AlertBox.Show(e.Message.Content);
chatBox.DataSource.Add(new Message("Hello!", null, new User("2", "Bot")));
this.Controls.Add(chatBox);

Constructors

ChatBox()

Creates a new instance of ChatBox.

The current User is initialized to a default user named "User" with a generated id.

Example:

var chatBox = new ChatBox();
chatBox.User = new User { Id = "1", Name = "Alice" };

Properties

AvatarVisible

Boolean: Returns or sets whether the message avatar is visible. (Default: True)

Value: true to show the user avatar next to messages; otherwise false. The default is true.

Changing this value does not update messages already displayed.

Example:

chatBox.AvatarVisible = false;

DataSource

ObservableCollection<Message>: Returns the collection of messages displayed in the chat box.

Value: An ObservableCollection of Message objects, created on first access.

Changes to the collection are reflected in the control: adding a message renders it (and scrolls it into view), removing it disposes its control, clearing removes all messages, and moving reorders them. Messages without a User are assigned the current User, and messages without a Timestamp are stamped with the current time.

Example:

var bot = new User("bot", "Assistant");
chatBox.DataSource.Add(new Message("Hi, how can I help?", null, bot));
chatBox.DataSource.RemoveAt(0);

ForeColor

Color: Returns or sets the color of the message input text box.

Value: A Color applied to the message input text box.

Unlike the inherited ForeColor, this property reads and writes the BackColor of the inner message input text box.

Example:

chatBox.ForeColor = Color.WhiteSmoke;

InputVisible

Boolean: Returns or sets whether to show the message input panel (text box and send button). (Default: True)

Value: true to show the input panel; otherwise false. The default is true.

Hide the input panel to use the ChatBox as a read-only message viewer.

Example:

chatBox.InputVisible = false;

Multiline

Boolean: Returns or sets whether the message input text box is multiline. (Default: False)

Value: true to allow multiple lines of input; otherwise false. The default is false.

When true, the text box accepts returns and automatically resizes its height to fit the text; pressing Enter without modifiers still sends the message.

Example:

chatBox.Multiline = true;

ReadOnly

Boolean: Returns or sets whether the chat control is in read-only mode. (Default: False)

Value: true to make the message input read-only and disable the send button; otherwise false. The default is false.

Messages can still be added in code through DataSource.

Example:

chatBox.ReadOnly = true;

ScrollBars

ScrollBars: Returns or sets the type of scroll bars to display in the messages area of the ChatBox. (Default: Both)

Value: One of the ScrollBars values. The default is Both.

Hides the inherited ScrollBars and applies the value to the inner panel that hosts the messages.

Example:

chatBox.ScrollBars = ScrollBars.Vertical;

TimestampFormat

String: Returns or sets the format string used to display message timestamps. (Default: "HH:mm")

Value: A standard or custom DateTime format string. The initial value is "HH:mm".

Note that the designer DefaultValueAttribute is declared as "HH:mmm", which differs from the initial value "HH:mm".

Example:

chatBox.TimestampFormat = "dd/MM HH:mm";

TimestampVisible

Boolean: Returns or sets whether to display the message timestamp. (Default: True)

Value: true to show the timestamp of each message; otherwise false. The default is true.

Changing this value does not update messages already displayed. See also TimestampFormat.

Example:

chatBox.TimestampVisible = false;

Tools

ComponentToolCollection: Returns the collection of tools displayed in the message input box of the ChatBox.

Value: The ComponentToolCollection of the inner message input text box.

Handle ToolClick to respond to clicks on the tools.

Example:

chatBox.Tools.Add(new ComponentTool { Name = "emoji", ImageSource = "icon-emoji", ToolTipText = "Emoji" });

User

User: Returns or sets the current user of the ChatBox. (Default: null)

Value: The User that authors messages typed in the input box. The initial value is a user named "User" with a generated id and a default avatar.

Messages from this user are aligned to the right; messages from other users are aligned to the left. Changing the user does not update messages already displayed.

Example:

chatBox.User = new User("42", "Alice", "Images/alice.png");

Watermark

String: Returns or sets the watermark text to show when the message input text box is empty. (Default: "Type a message...")

Value: The watermark text. The default is "Type a message...".

Example:

chatBox.Watermark = "Ask me anything...";

Methods

Clear()

Clears the chat box messages.

Clears the DataSource collection, which removes and disposes all message controls.

Example:

chatBox.Clear();

Dispose(disposing)

Clean up any resources being used.

Parameter	Type	Description
disposing	Boolean	true if managed resources should be disposed; otherwise, false.

ExportAsJson()

Exports the chat history as a JSON string.

Returns: String. A JSON string containing the serialized messages in DataSource.

Example:

string json = chatBox.ExportAsJson();
Application.Session.ChatHistory = json;

OnFormatMessage(e)

Invokes the FormatMessage event. Fires when a message is posted to the ChatBox.

Parameter	Type	Description
e	MessageEventArgs	The event data.

OnMessageActionInvoke(e)

Invokes the MessageActionInvoke event. Fires when the user performs an action on a message.

Parameter	Type	Description
e	Object	The dynamic event data.

OnRenderMessageControl(e)

Invokes the RenderMessageControl event. Fires when a Message control is needed.

Parameter	Type	Description
e	RenderMessageControlEventArgs	The event data.

OnSendingMessage(e)

Invokes the SendingMessage event. Fires before a message is sent.

Parameter	Type	Description
e	SendingMessageEventArgs	The event data.

OnSentMessage(e)

Invokes the SentMessage event. Fires after a message has been sent.

Parameter	Type	Description
e	MessageEventArgs	The event data.

OnTypingEnd(e)

Invokes the TypingEnd event. Fires when the user stops typing.

Parameter	Type	Description
e	EventArgs	The event data.

OnTypingStart(e)

Invokes the TypingStart event. Fires when the user starts typing.

Parameter	Type	Description
e	EventArgs	The event data.

Events

FormatMessage

FormatMessageEventHandler Fired when a message is posted to the ChatBox, before it is rendered.

Use this event to save information related to the type of control to render, for example by setting ContentType or UserData.

Example:

chatBox.FormatMessage += (s, e) =>
{
    if (e.Message.Content.StartsWith("http"))
        e.Message.ContentType = "link";
};

MessageActionInvoke

EventHandler<Object> Fired when the user performs an action on a message.

The event data is a dynamic object describing the action.

Example:

chatBox.MessageActionInvoke += (s, e) => AlertBox.Show("Message action invoked.");

RenderMessageControl

RenderMessageControlEventHandler Fired when a Message needs a control to display its content.

Set Control to provide a custom control. When no control is provided, a selectable label showing Content is used.

Example:

chatBox.RenderMessageControl += (s, e) =>
{
    if (e.Message.ContentType == "image")
        e.Control = new PictureBox { ImageSource = e.Message.Content };
};

SendingMessage

SendingMessageEventHandler Fired before a message is sent.

Set Cancel to true to prevent the message from being rendered and SentMessage from firing. The event is raised only for messages submitted by the user through the chat UI (pressing Enter or clicking the send button); messages added in code to DataSource don't raise it.

Example:

chatBox.SendingMessage += (s, e) =>
{
    if (String.IsNullOrWhiteSpace(e.Message.Content))
        e.Cancel = true;
};

SentMessage

MessageEventHandler Fired after a message has been sent and rendered in the ChatBox.

Fires for every message added to DataSource, whether typed by the user or added in code. Use IsChatBoxUser to determine whether the message belongs to the current User.

Example:

var botUser = new User("bot", "Echo Bot");
chatBox.SentMessage += (s, e) =>
{
    if (e.IsChatBoxUser)
        chatBox.DataSource.Add(new Message("Echo: " + e.Message.Content, null, botUser));
};

ToolClick

ToolClickEventHandler Fired when a ComponentTool in the Tools collection is clicked.

Handlers are attached to the ToolClick event of the inner message input text box.

Example:

chatBox.Tools.Add(new ComponentTool { Name = "attach", ImageSource = "icon-attach" });
chatBox.ToolClick += (s, e) =>
{
    if (e.Tool.Name == "attach")
        AlertBox.Show("Attach clicked");
};

TypingEnd

EventHandler Fired when the user stops typing.

Fires when the message is sent with Enter or when the input box loses focus while typing.

Example:

chatBox.TypingEnd += (s, e) => labelStatus.Text = "";

TypingStart

EventHandler Fired when the user starts typing in the message input box.

Example:

chatBox.TypingStart += (s, e) => labelStatus.Text = "Typing...";

Implements

Name	Description
IUserData
IBindableComponent
IContainerControl
IDropTarget
IWisejComponent
IWisejControl
IWisejSerializable