Skip to content

The VCL component ​

TVclHelpChatAI (unit Vcl.HelpChatAI, package HelpChatAIVcl) is a non-visual component: drop it on a form, set Active := True, and it takes care of the bubble, F1, the screen context and the chat panel. The panel itself is TVclHelpChatAIPanel, a control hosting a WebView2 (TEdgeBrowser) — you normally never touch it directly.

Activating it ​

pascal
HelpChatAI.Active := True;

Activation reads the configuration, takes the engine of the component's Profile and starts it, starts the local HTTP server that serves the chat page, joins the help viewer and the F1 handling of the application, and places the bubble on the host form. A failure on the way - a named configuration file that is missing, a server that cannot start - raises and leaves the component inactive. Setting Active := False (or freeing the component) closes the server and lets the engine go.

The engine belongs to the profile, not to the component: two components with the same Profile (two instances of one form) hold the same engine, with one index, one conversation and one model in use, and it stops - workers with a bounded wait, conversation saved if persistence is on - when the last of them deactivates. That is why what the user changes in the panel (the model, the language) is found in Engine.Settings and not in Settings, which stay what the application configured. An action a reply calls after its assistant was deactivated is answered "cancelled" at once instead of running on a form that is going away. See Assistants and models.

Active set at design time is streamed and applied when the form is loaded at runtime.

Opening the chat ​

MethodWhat it does
OpenOpens the panel with the context of the current screen
OpenForCurrentScreenOpens it and asks the localized question about this screen (what F1 does)
OpenForHelp(AKeyword, AContext)What the help system calls: the current context, with that keyword or context id
OpenWithQuestion(AText, ASend)Opens it and sends AText (or just pre-fills it when ASend is False)
Close / Toggle / IsPanelVisibleThe rest of the window management

OpenWithQuestion is how you add your own entry points — a menu item "Ask the assistant about invoices", a button in a toolbar:

pascal
HelpChatAI.OpenWithQuestion('Come si registra una fattura di acquisto?');

The same question asked twice within 1.5 seconds is shown but sent once: a key repeat or a request routed twice cannot spend two model calls.

Where the chat appears ​

By default the panel lives in a small tool window anchored to the bottom-right corner of the host form, which remembers where the user left it (RememberPanelPosition, per application, per user and per profile).

It works from a modal form too

Press F1 on a form opened with ShowModal and the chat comes in front of it and stays usable. That takes some care on Windows — a modal form is kept above every window with the same owner, and the others are disabled while it is up — so the component makes the modal form the owner of its window for as long as it lasts, and hands it back when the form closes. You do not have to do anything; it is worth knowing only because the page reloads when that happens.

Embedding the chat in your own window ​

Everything visible is inside the browser, so what an application really decides is where the chat appears. Give it any TWinControl and it fills that instead:

pascal
procedure TMainForm.HelpChatBeforeShowHelp(Sender: TObject; var AContainer: TWinControl);
begin
  if EmbeddedCheck.Checked then
  begin
    ChatPanel.Visible := True;    // an alRight TPanel of this form
    ChatSplitter.Visible := True;
    AContainer := ChatPanel;
  end;
  // leaving AContainer nil keeps the component's own window
end;

procedure TMainForm.HelpChatBeforeHideHelp(Sender: TObject);
begin
  ChatPanel.Visible := False;     // the user closed the chat: hide your container
  ChatSplitter.Visible := False;
end;
EventWhen
OnBeforeShowHelp(Sender; var AContainer)Before showing: arrives with the Container property, set it to your control
OnAfterShowHelpThe chat is visible in its container
OnBeforeHideHelpThe user closed it (✕, Esc, Close): hide your container here
OnAfterHideHelpAfter hiding

The Container property does the same thing without an event, when the place never changes. Remembering size and position is the job of whoever hosts the chat: the component's own window does it, a container of yours is yours to persist.

The bubble and F1 ​

ShowBubble puts a round button with the assistant icon in the bottom-right corner of the form the assistant lives on: HostForm when set, else the form that owns the component (the form of its frame, for a component on a frame), else Application.MainForm for a component on a data module. HandleF1 and RegisterHelpViewer decide what F1 does — the full story is in F1 and the screen context.

The bubble is a control with a window of its own, and that is not a detail. It used to be a TSpeedButton, and on a real form it vanished: a graphic control is painted on the canvas of its parent and the VCL keeps it below every windowed control of the same parent, so a grid, a page control or a panel over that corner simply hid it, and BringToFront could not help. The one you get now raises its window and asks to be raised again whenever the form adds a control or is resized.

Moving the bubble ​

The bottom-right corner is where the bubble starts, not where it has to stay: the user can drag it anywhere on its form. A press that moves less than the drag threshold of Windows is still a click and opens the chat; one that moves farther moves the bubble, and the release never opens anything. Dropped, the bubble keeps its distance from the corner it is nearest to - left at the top left, it stays at the top left when the form grows; near the bottom right, it follows that corner as it does by default - and it never leaves the form, a smaller one included (the bubble of the main form may, with BubbleStayOnTop).

With RememberPanelPosition the place is remembered next to the position of the chat window, in the same helpchatai-ui.json, one place per form: the bubble of the main form and the one of the orders form each go back where they were left, and every instance of one form shares it. The distances are stored at 96 DPI, so a form on a monitor with another scaling shows the bubble at the same distance. BubbleDraggable := False keeps it where it is, and ResetBubblePosition takes it back to the corner and forgets the place - a command for a menu of yours, for a user who lost it behind something.

From Windows 8 on that window is a layered one, with an alpha channel per pixel: the disc and the icon are drawn with GDI+ in antialiasing and Windows blends their edge with whatever lies under the bubble, and a click on a transparent corner reaches the control underneath. That needs the Windows 8 entry of the application manifest, which the default_app.manifest of Delphi carries. Where it is not available - the form designer, Windows 7, a manifest without it - the bubble is cut to a circle by a window region, as before 1.5.0, and only its rim is hard.

Keeping the bubble in front ​

An application whose secondary forms open maximized hides the bubble of the main form behind them. BubbleStayOnTop := True on the assistant of the main form keeps it in front of every form of the application, modal ones included, and clickable while a modal form is up. The bubble becomes a small window of its own, owned by the main form: it follows the form when it moves, hides when it is minimized, and goes behind the windows of another application when that one is active.

The user may then drag it anywhere on the monitor of the main form, outside the form too: it stays anchored to the nearest corner of the form and is never taken off the work area of the screen - a form moved to the edge pushes it back. On any other form the property is ignored.

TFmxHelpChatAI has the same property, on Windows: there the bubble becomes a small borderless transparent form, so its round edge blends with whatever lies under it. On the other platforms it is ignored.

Changing the icon ​

The usual Delphi contract, on the component:

PropertyWhat it does
ImagesYour image list. Leave it nil to use the icons shipped with the component
ImageIndexThe icon by position
ImageNameThe icon by name, which is what the built-in list expects

In the Object Inspector both ImageIndex and ImageName drop down the icons themselves, drawn: the editor the IDE gives the standard controls is not offered to a component that is not one of them, so the library registers its own.

pascal
HelpChatAI.ImageName := 'AIAssistant_Female';

Ten icons are compiled in, each with a member of THelpChatAssistantIcon (unit HelpChatAI.Assistant) whose position is its ImageIndex in the built-in list, and a constant with its ImageName:

THelpChatAssistantIconImageIndexImageNameConstant
haiAIMale0AIAssistant_MaleHELPCHAT_ICON_AI_MALE (the default)
haiAIFemale1AIAssistant_FemaleHELPCHAT_ICON_AI_FEMALE
haiMale2Assistant_MaleHELPCHAT_ICON_MALE
haiFemale3Assistant_FemaleHELPCHAT_ICON_FEMALE
haiBusinessman4BusinessmanHELPCHAT_ICON_BUSINESSMAN
haiBusinesswoman5BusinesswomanHELPCHAT_ICON_BUSINESSWOMAN
haiCustomerSupport6CustomerSupportHELPCHAT_ICON_CUSTOMER_SUPPORT
haiManager7ManagerHELPCHAT_ICON_MANAGER
haiVoicePresentation8VoicePresentationHELPCHAT_ICON_VOICE_PRESENTATION
haiPortraitMode9PortraitModeHELPCHAT_ICON_PORTRAIT_MODE

The first two are the assistant with the chat bubble and its spark, the next two the same faces without it; the other six come from the flat-color-icons set (MIT). HELPCHAT_ICON_NAMES[haiManager] gives the name of a member, and HelpChatAssistantIconOf the member of a name. The configuration editor shows them all, drawn. Each ships in nine sizes from 16 to 192 pixels, and the bubble picks through a TVirtualImageList: having a window it knows its own DPI, so a 150% or 200% monitor gets a crisp icon instead of a stretched one. The disc takes its colour from the active VCL style: the bubble control (TVclHelpChatAIBubble) has a BubbleColor to override it, but the component creates its bubble itself and does not expose it.

Naming the assistant ​

Two properties decide what the user reads, and both are empty by default - which does not mean "nothing", it means "the word of the current language":

PropertyEmpty gives youWhat it is
CaptionHelp (Aiuto in Italian)The title of the window the chat opens in
AssistantNameAssistant (Assistente)The name in the header of the panel, and the title of the page
pascal
HelpChatAI.Caption := 'Assistenza clienti';   // the window
HelpChatAI.AssistantName := 'Aida';           // the header of the chat

The header draws the icon of the bubble to the left of the name, so the assistant looks the same wherever the user meets it: change Images, ImageIndex or ImageName and both follow. The icon reaches the page as a data: URI the component renders from your image list - nothing is fetched over the network, and the content policy of the page allows no other source for an image.

Both properties can be changed while the panel is open; the header updates without reloading the conversation. Leave them empty unless you have a reason: an application translated into a language the library knows gets the right word for free, and a name written in the Object Inspector is the same in every language. Left empty, they also follow the user when the language of the chat is switched from the flag of the panel.

The window is not the assistant

Caption is a window title - the user reads it in the taskbar and in Alt+Tab, so "Help" says what the window is for. AssistantName is a name, and it belongs inside. When the chat is embedded in a container of yours there is no window, so only AssistantName shows.

Trying it at design time ​

Right-click the component on the form: Configuration... (also a double click) opens the configuration editor - the files, the profiles, the models, and where every value comes from - Test HelpChat... opens the real chat in a modal window, Check configuration... answers "would this work?" without building the application, and Rebuild documentation index... builds help-index.json. All of it, and the property editors of the Object Inspector, is described in the component editor.

Dictating the question ​

A microphone sits left of the question box: press it and talk, press it again to stop. Sending the question stops it too. The text lands in the box and stays there, so the user rereads it and sends it: nothing leaves on its own.

VoiceEngine chooses who listens, and what you choose is what runs — an engine that does not work says so, it is never swapped underneath:

ValueWhat you get
hveNoneNo dictation: nothing is asked of Windows, no microphone button
hveSystemDictation (default)The dictation of Windows, the one Win+H starts. Windows types into the box itself, so the component sees nothing and only knows that it asked
hveRecognizerWindows.Media.SpeechRecognition: the box fills while the user talks, the button pulses, OnVoiceText sees every piece before it lands

The dictation is the default because it works wherever Win+H works. The recognizer is the better citizen, since the text passes through your code, but it needs the online speech recognition consent of Windows, and on recent Windows 11 builds it can start, hear the voice and transcribe nothing at all. No application can give that consent: with hveRecognizer the component checks it, and the first time it is missing it explains what is needed and opens that page of the Windows settings. Handle OnVoiceConsentNeeded to say it your own way.

pascal
procedure TMainForm.HelpChatVoiceText(Sender: TObject; var AText: string;
  const AFinal: Boolean);
begin
  if AFinal then
    AText := MyGlossary.Fix(AText);   // "vi ci el" -> "VCL"
end;

In Delphi 10.4 only hveSystemDictation works, because the RTL translates those WinRT APIs from Delphi 11 on: ask for the recognizer there and the button stays hidden.

Colours ​

With FollowVclStyle (the default) the panel is coloured after the active VCL style and follows a style change at runtime, including while the chat is open. OnGetTheme lets you adjust the result — a brand accent, a different font. See Colours and theming.

Actions ​

Actions is the registry of what the assistant may do in your application, available from the component's constructor:

pascal
HelpChatAI.Actions.Add('open_screen', 'Brings a screen of the application to the front.',
  [THelpChatActionParam.Create('name', 'Screen name')],
  procedure(const AArgs: THelpChatActionArgs; var AResult: string)
  begin
    PageControl.ActivePage := FindTab(AArgs.AsString('name'));
    AResult := 'Opened the ' + ... + ' screen.';
  end, False);   // changes nothing: no confirmation

See Actions for the whole picture, including confirmation.

Letting the user attach a document ​

pascal
HelpChatAI.Settings.Attachments.Enabled := True;

A paper clip appears next to the question box, and the PDF, image or text file the user picks - or drops on the panel - reaches the model with the next question. Off by default, because what the user attaches leaves the machine. See Attaching documents.

The header of the panel ​

Next to the name, the panel shows copy, PDF and clear, the flag of the language when there is more than one to choose from, and as the last button on the right the icon of the model in use, which opens the list ("Change model") when there is more than one. There is no close button in the page: the window of the chat has its own, and an embedded panel is closed the way your form decides (Escape still asks the host to close it).

Everything at a glance ​

The full list of properties, events and methods is in the TVclHelpChatAI reference.

What the component needs from you ​

  • WebView2Loader.dll next to the executable (see Installation).
  • A HelpKeyword on the screens you want the assistant to recognise.
  • Nothing else: no form to design, no thread to manage, no hook of your own on the message loop.

Several assistants in one application

Each form may have its own assistant: a general one on the main form, an expert on the order form. They are all active at once, each with its bubble on its own form, and F1 goes to the assistant of the active form - or, on a form that has none (a dialog, a print preview), to the one whose form was active last. One help viewer and one hook of the message loop serve them all. TVclHelpChatAI.CurrentAssistant says which one is in front of the user. Two assistants on the same form work too; F1 on that form can only go to one of them - left alone, the one activated first when both become active while the form loads, see which assistant answers - so set HandleF1 (and RegisterHelpViewer) to False on the other to make the choice yours.

Released under the Apache License 2.0