TTMSFNCChat

The TTMSFNCChat is a control to show chat messages. Underlying it's using a TTMSFNCTableView.

Adding messages

Addig messages can be done in multiple ways:

• If the ShowMessageField property is enabled, a memo and a send button will be shown at the bottom of the component. Whenever the send button or the return key is pressed while typing, a message will be added to the ChatMessages collection. Implement the OnBeforeSendMessage and OnAfterSendMessage events for more control over the messages added by the user.

• By adding to the ChatMessages collection directly:

procedure TForm1.Button1Click(Sender: TObject);
var
  itm: TTMSFNCChatItem;
begin
  itm := chat.ChatMessages.Add;
  itm.Text := 'How was your day?';
  itm.Title := 'Mom';
  itm.Fill.Color := gcGray;
  itm.MessageLocation := cmlLeft;
end;

• By using the AddMessage helper function(s)

procedure TForm1.Button1Click(Sender: TObject);
var
  itm: TTMSFNCChatItem;
begin
  itm := chat.AddMessage('How was your day?', 'Mom', cmlLeft);
  itm.Fill.Color := gcGray;
end;

Images

There are two options to add images:

• Using the AddImage/AddImageWithName helper functions.
• Manually add images by formatting the Text property of the item.

procedure TForm1.Button1Click(Sender: TObject);
begin
  TMSFNCChat1.AddImage('path to image');
end;

or

procedure TForm1.Button1Click(Sender: TObject);
begin
  TMSFNCChat1.AddImageWithName('path to image', 'MyImageNameInContainer');
end;

The difference between AddImage and AddImageWithName is minimal. If a BitmapContainer is assigned and the AddImagesToBitmapContainer property is enabled then the images are saved to the assigned BitmapContainer. With AddImageWithName you can specify the name with should be used when added to the BitmapContainer. By using AddImage the name will be extracted from the AImagePath parameter.

If no BitmapContainer is assigned the images will be converted to base64 automatically and painted that way. Be aware that by doing this the control might become slow.

Keep in mind

For WEB platform without a BitmapContainer you'll need to use a base64 encoded image as the path.

Files

Similar to adding images, files can also be added by:

• Using the AddFile helper function.
• Manually by formatting the Text property of the item.

The first AFilePath parameter of the AddFile function will serve as the URL to the file. The second AFileName parameter is the file name that is displayed.

procedure TForm1.Button1Click(Sender: TObject);
begin
  //This works on desktop platforms only:
  TMSFNCChat1.AddFile('file://path_to_my_local_file', 'my local file');
end;

Customizing the look

Message bubbles

Message bubbles can be drawn either around the message title, icon or text or just around the text. This can be modified by setting the MessageStyle property.

Furthermore, for each new message added via the AddMessage calls, the DefaultLeftItem and DefaultRightItem settings are applied to the new item.

Message timestamps can be additionally enabled by setting the MessageTimestamp.Show property to True. The poisitoning of the timestamp as well as the date and time format can be set via the MessageTimestamp.Position and MessagetimeStamp.Format properties.

Send button

Underlying the send button is a TTMSFNCToolBarButton. The capabilities from TTMSFNCToolBarButton can be used to customize the sending button programmatically as access to the send button is provided as a public property.

For example, to change the button graphic and to add a hint, you can do the following:

procedure TForm1.FormCreate(Sender: TObject);
begin
  TMSFNCChat1.SendButton.Bitmap.LoadFromFile('path to file');
  TMSFNCChat1.SendButton.ShowHint := True;
  TMSFNCChat1.SendButton.Hint := 'Send';
end;

For a WhatsApp-like rounded send button implement the OnGetSendButtonRect event.

procedure TForm1.FormCreate(Sender: TObject);
begin
  TMSFNCChat1.Appearance.MinEntryBoxHeight := 30;
  TMSFNCChat1.SendButton.Appearance.NormalFill.Color := gcLightgray;
  TMSFNCChat1.SendButton.Appearance.Rounding := TMSFNCChat1.Appearance.MinEntryBoxHeight div 2;
  TMSFNCChat1.SendButton.StretchBitmapIfNoText := False;
  TMSFNCChat1.SendButton.AutoBitmapSize := False;
  TMSFNCChat1.SendButton.BitmapSize := 15;
  TMSFNCChat1.OnGetSendButtonRect := HandleGetSendButtonRect;
end;

procedure TForm1.HandleGetSendButtonRect(Sender: TObject; var ARect: TRectF);
var
  t: Single;
begin
  t := ARect.Top;
  ARect.Top := ARect.Top + ((ARect.Bottom - t - TMSFNCChat1.SendButton.Width) / 2);
  ARect.Bottom := ARect.Bottom - ((ARect.Bottom - t - TMSFNCChat1.SendButton.Width) / 2);
end;

Attachment button

There is an optional attachment button. To show this attachment button, set the Appearance.ShowAttachmentButton property to True.

The look and feel of this button can be modified programmatically similar to the SendButton. Access to the underlying TTMSFNCToolBarButton control is provided via the AttachmentButton public property.

Message/Entry box

The Memo public property provides access to the underlying TMemo/TWebMemo.

Reload

The TTMSFNCChat also supports a reload mechanism, which is visually represented as a circular progressbar (optionally marquee progress) that waits until the chat reload process is finished. Below is a sample that demonstrates this.

1. Set TTMSFNCChat1.Reload.Enabled := True; which will enable the ability to reload the list.

2. Reload progress is started by dragging the list down, which calls the OnStartReload event, or by programmatically calling StartReload.

3. In the OnStartReload event you can start a thread which performs a task.

4. After the thread is finished, call TMSFNCChat1.StopReload; which will then call the OnStopReload event.

Drag and drop

The TTMSFNCChat is capable of detecting when files are dragged over the control. When this happens the OnFileDragOver event is triggered. The AAllow parameter let's you to allow the acceptance of dragged files. By default the files are rejected.

After setting the AAllow parameter to True, upon dropping the files on the control the OnFileDrop event will trigger. The AFileList parameter contains the file list.

Important methods, properties and events

Properties

Property name	Description
AddImagesToBitmapContainer	If a BitmapContainer is assigned and this property is enabled then the images are saved to the assigned BitmapContainer
Appearance	Various appearance settings
AllowMultiSelect	By defeault item selection is not enabled when clicking on a chat message. If AllowMultiSelect is set to True, then items can be selected.
AttachmentButton	The attachment button control. Visible when ShowMessageField and Appearance.ShowAttachmentButton is enabled. It is a TTMSFNCToolBarButton.
ChatMessages	A collection of chat items.
ChatInteraction	The various interaction capabilities of the chat.
DefaultLeftItem	Settings from this property is assigned to each new item added with left alignment via the AddMessage call and by doing ChatMessages.Add.
DefaultRightItem	Settings from this property is assigned to each new item added with right alignment via the AddMessage call.
Footer	The footer of the chat, which has optional HTML formatted text.
Header	The header of the chat, which has optional HTML formatted text and acts as a container for the edit, filter, back and done buttons.
Memo	The memo control. Visible when ShowMessageField is enabled.
MessageTimestamp	Timestamp settings: - Show: Enables showing timestamp on messages - Format: Format of the timestamp - Position: Position of the timestamp relative to the message.
Reload	The reload settings of the chat after performing a swipe gesture from top to bottom on the chat.
SendButton	The send button control. Visible when ShowMessageField is enabled. It is a TTMSFNCToolBarButton.
ShowMessageField	If set to True the Memo and SendButton controls become visible at the bottom of the control.
VerticalScrollBarVisible	If set to True the vertical scrollbar of the chat message area becomes visible.

Appearance

Property name	Description
MaxEntryBoxHeight	Maximum allowed height of the memo when typing.
MessageStyle	Defines which parts of the message the message styling applies to. - cmsAll: The style settings apply to the icon + title + message text. - cmsTextOnly: The style settings apply to the text only.
MinEntryBoxHeight	Minimum allowed height of the memo when typing.
ShowAttachmentButton	Show the optional attachment button.
SideMargin	Sets the space between the border and the messages.
Spacing	Spacing value between chat messages.
TitleFont	Font settings for the title of message items.

Methods

Method name	Description
AddFile(AFilePath: string; AFileName: string; ATitle: string = ''; ALocation: TTMSFNCChatMessageLocation = cmlRight)	Helper function to add a file automatically as a message.
AddImage(AImagePath: string; AText: string = ''; ALocation: TTMSFNCChatMessageLocation = cmlRight; AImageWidth: Integer = 150)	Helper function to add an image automatically as a message.
AddImage(AImagePath: string; AText: string; ATitle: string; ALocation: TTMSFNCChatMessageLocation = cmlRight; AImageWidth: Integer = 150)	Helper function to add an image automatically as a message.
AddImageWithName(AImagePath: string; AImageName: string; AText: string = ''; ALocation: TTMSFNCChatMessageLocation = cmlRight; AImageWidth: Integer = 150)	Helper function to add an image automatically as a message.
AddImageWithName(AImagePath: string; AImageName: string; AText: string; ATitle: string; ALocation: TTMSFNCChatMessageLocation = cmlRight; AImageWidth: Integer = 150)	Helper function to add an image automatically as a message.
AddMessage(AText: string; ALocation: TTMSFNCChatMessageLocation = cmlRight)	Helper function to add an item to the ChatMessages collection. It returns with the item added.
AddMessage(AText: string; ATitle: string; ALocation: TTMSFNCChatMessageLocation = cmlRight)	Helper function to add an item to the ChatMessages collection. It returns with the item added.
Clear	Clears the ChatMessages collection.
ClearSelection	Clears the current item selection.
DetailControlActive: Boolean	Returns a Boolean to determine if the detail contorl is active or not.
DisableInteraction	Disables interaction with the chat items.
DisableInputControls	Disables the input controls (memo and send button).
EnableInteraction	Enables interaction with the chat items.
EnableInputControls	Enables the input controls (memo and send button).
HideDetailControl	Hides the detail control.
InitSample	Initializes a sample conversation.
ReloadProgress: Single	The progress that indicates the reload time when the reload progress mode is tvrpmManual.
ScrollToItem(AItemIndex: Integer)	Scrolls the tableview to a specific item based on an item index.
SelectedItemCount: Integer	Returns the selected chat item count.
SelectItem(AItemIndex: Integer)	Selects a specific item based on an item index.
ShowDetailControl(AItemIndex: Integer = -1)	Shows the detail control assigned to a specific item. When the AItemIndex = -1 the DefaultItem detail control is used, when it is assigned.
StartReload	Starts a reload operation in the chat.
StopReload	Stops the active reload operation.
UpdateReloadProgress(AProgress: Single; AAutoStopReload: Boolean = True)	Updates the reload progress when the reload progress mode is set to tvrpmManual.
XYToChatItem(X, Y: Single): TTMSFNCChatItem	Returns the chat item at the (X, Y) coordinates.
XYToItemIndex(X, Y: Single): Integer	Returns the item index at the (X, Y) coordinates.

Events

Event name	Description
OnAfterDrawMessage	Event triggered after the message item is drawn.
OnAfterDrawMessageIcon	Event triggered after the message icon is drawn.
OnAfterDrawMessageText	Event triggered after the message text is drawn.
OnAfterDrawMessageTitle	Event triggered after the message title is drawn.
OnAfterDrawTimestamp	Event triggered after drawing the message timestamp.
OnAfterSendMessage	Event triggered after adding the message from the send button click to the ChatMessages collection.
OnAttachmentButtonClick	Event triggered when the attachment button is clicked.
OnBeforeDrawMessage	Event triggered before the message item is drawn.
OnBeforeDrawMessageIcon	Event triggered before the message icon is drawn.
OnBeforeDrawMessageText	Event triggered before the message text is drawn.
OnBeforeDrawMessageTitle	Event triggered before the message title is drawn.
OnBeforeDrawTimestamp	Event called before drawing the message timestamp.
OnBeforeMessageHideDetailControl	Event called before the detail control of an item is hidden.
OnBeforeMessageShowDetailControl	Event called before the detail control of an item is shown.
OnBeforeSelectChatItem	Event triggered before selecting a chat item.
OnBeforeSendMessage	Event called before adding the message from the send button click to the ChatMessages collection.
OnFileDragOver	Event triggered when files are dragged over the message area.
OnFileDrop	Event triggered when files are dropped in the message area.
OnFooterAnchorClick	Event called when an anchor is clicked in the footer.
OnGetSendButtonRect	Event called when calculating the placement rectangle of the send button.
OnHeaderAnchorClick	Event called when an anchor is clicked in the header.
OnLongPressItem	Event called when a message item is long pressed.
OnMessageAnchorClick	Event triggered when an anchor is clicked in the message text.
OnMessageClick	Event triggered when a message is clicked.
OnMessageDblClick	Event triggered when the message item is double clicked.
OnMessageHideDetailControl	Event called when an item detail control is hidden.
OnMessageMouseLeave	Event triggered when the mouse leaves the message item.
OnMessageMouseEnter	Event triggered when the mouse enters the message item.
OnMessageShowDetailControl	Event called when an item detail control is shown.
OnMessageTitleAnchorClick	Event called when a message title anchor is clicked.
OnSendButtonClick	Event triggered when the send button is clicked.
OnStartReload	Event called when a reload operation is started.
OnStopReload	Event called when a reload operation is stopped.
OnVScroll	Event triggered on vertical scrolling.