Skip to content

TVclHelpChatAI reference ​

Unit Vcl.HelpChatAI · package HelpChatAIVcl · palette group Ethea HelpChat · Delphi 10.4 and later.

A non-visual component, one assistant of the application: it owns its transport, the bubble and the chat panel, and while Active it holds the engine of its Profile, which it shares with the other assistants of the same profile.

Published properties ​

PropertyTypeDefaultDescription
SettingsTHelpChatSettingsEverything the engine needs: provider, language, index, the model sections, Remote. See the Settings reference. At activation the configuration files are merged on top and a copy becomes the settings of the engine: a value changed here while active applies to the next activation
ActiveBooleanFalseAcquires the engine of the profile and starts it, starts the transport and the hooks. Set at design time it applies when the form is loaded at runtime
RegisterHelpViewerBooleanTrueRegister the chat as the help viewer of the application (ICustomHelpViewer): F1 on a control with help, Application.HelpKeyword, HelpShowTableOfContents
HandleF1BooleanTrueF1 opens the chat also where nothing declares help
Captionstring(empty)Title of the window the chat opens in when it is not embedded. Empty = the localized "Help" / "Aiuto"
Profilestring(empty)Which assistant this is: its section under "Profiles" in the configuration and the suffix of its files. Never shown. Empty = the default assistant
AssistantNamestring(empty)What the assistant is called, written in the header of the panel next to its icon. Empty = the localized "Assistant" / "Assistente". "AssistantName" in the configuration prevails
ShowBubbleBooleanTrueThe round button with the assistant icon, in the bottom-right corner of the host form
BubbleDraggableBooleanTrueThe user may drag the bubble to another place of its form: it keeps its distance from the nearest corner, and is found there again (The bubble)
BubbleStayOnTopBooleanFalseMain form only: the bubble stays in front of every form of the application, modal ones included, and may be dragged anywhere on the monitor (Keeping the bubble in front)
ImagesTCustomImageListnilImage list holding the bubble icon; nil uses the icons compiled into the component
ImageIndexTImageIndex0Bubble icon by position, kept in step with ImageName. 0 is the first built-in icon, the default assistant
ImageNameTImageName(empty)Bubble icon by name: with no Images, one of AIAssistant_Male, AIAssistant_Female, Assistant_Male, Assistant_Female, Businessman, Businesswoman, CustomerSupport, Manager, VoicePresentation, PortraitMode (HELPCHAT_ICON_NAMES). Setting one sets the other, as in the VCL controls: the name wins when both are set, and ImageIndex is used when the name finds nothing
VoiceEngineTHelpChatVoiceEnginehveSystemDictationWho dictates: hveNone (no microphone button), the dictation of Windows, or the speech recognizer
ConfigFileNameTFileName(empty)The configuration file. Empty = merge the three standard helpchatai.json on activation; named = that one and nothing else, raising EHelpChatConfigError if it is not there
ActionsEnabledBooleanTrueOffer the registered actions to the model
UseSharedActionsBooleanTrueOffer also the actions every assistant shares (HelpChatSharedActions); Settings.AllowedActions narrows both
EnabledCommandsTHelpChatCommandseverything but prompt and runThe slash commands the user may type. From code any command runs
PanelStyleSheetTFileName(empty)A CSS file of the application, added to the page of the chat after its own (a radius, a spacing, a hidden button: Inside the panel); it reaches OnGetTheme as ATheme.StyleSheet. Read at activation; a named file that is not there raises EHelpChatConfigError
PdfStyleSheetTFileName(empty)The stylesheet a saved PDF is laid out with; empty = the one built into the library. A named file that is not there raises EHelpChatConfigError
PdfHeaderFileTFileName(empty)The template of the band at the top of every sheet, with its placeholders
PdfFooterFileTFileName(empty)The template of the band at the foot
FollowVclStyleBooleanTrueColour the panel after the active VCL style, and follow style changes
RememberPanelPositionBooleanTrueReopen the own window where the user left it, and show the bubble where it was dragged to
ContainerTWinControlnilWhere the chat is embedded; nil = the component's own window. At design time only the controls that can hold another one are offered
PanelWidthInteger400Width of the own window at 96 dpi (scaled to the monitor)
PanelHeightInteger600Height of the own window at 96 dpi

The icon of Images, ImageIndex and ImageName is also the one the panel draws in its header, left of AssistantName.

Published events ​

EventSignatureWhen
OnGetContext(Sender; var AContext: THelpChatContext)The screen context has been built and can be refined
OnGetTheme(Sender; var ATheme: THelpChatTheme)The colours have been derived and can be adjusted; ATheme.StyleSheet carries the CSS of PanelStyleSheet and can be changed too
OnBeforeShowHelp(Sender; var AContainer: TWinControl)Before showing: set AContainer to embed the chat
OnAfterShowHelp(Sender)The chat is visible
OnBeforeHideHelp(Sender)The user closed it: hide your container
OnAfterHideHelp(Sender)After hiding
OnModelChanged(Sender)The user switched model in the panel (the badge of the header, or /use), or code did with SelectModel; on the main thread. RunSettings.ActiveModelName is the new one: the place to check that it has a key, and to ask for it
OnActionConfirm(Sender; const AName; const AArgs; var AAllow)An action marked Confirm is about to run; without a handler the confirmation dialog asks
OnActionExecuted(Sender; const AName; const AOutcome; const AResult)After every action
OnPdfInfo(Sender; var AInfo: THelpChatPdfInfo)Before a document is printed: correct the application name, the version, the user or the free Extra field the bands show
OnDecryptSecret(Sender; const AName, AValue; var AResult; var AHandled)A secret kept encrypted in the configuration is about to be used (the key of a provider, Remote.AppKey, Remote.UserToken): hand back the value to use. Runs on the worker thread - see Security and privacy
OnBuildSystemPrompt(Sender; const AContext: THelpChatContext; const ALanguage: THelpChatLanguage; var APrompt: string)The last word on the system prompt of each request, already built: change it or replace it. The rule about the actions is added after it. Runs on the worker thread, not inside the IDE - see the texts of the prompt
OnLogEvent(Sender; const AEntry: THelpChatLogEntry)Every entry of the log at Settings.LogLevel, on the thread that wrote it, one call at a time. HelpChatAI.Log in the uses - see Logging
OnOpenLink(Sender; const AUrl; var AHandled)A link is leaving the panel; set AHandled to open it yourself instead of the system browser
OnVoiceText(Sender; var AText; const AFinal)Dictated text on its way to the box: correct it, or empty it to drop it. AFinal is False for a hypothesis
OnVoiceConsentNeeded(Sender; var AHandled)The recognizer needs the online speech consent; set AHandled to explain it your way

Methods ​

MethodDescription
OpenOpens the panel with the context of the current screen
OpenForCurrentScreenOpens it and asks the localized question about this screen (F1)
OpenForHelp(AKeyword, AContext)Opens it for a specific keyword or help context id
OpenWithQuestion(AText, ASend = True)Opens it and sends AText, or only pre-fills it
CloseHides the chat (the conversation stays)
ToggleOpen if closed, close if open
Assign(ASource)Copies every published property of another TVclHelpChatAI but Active and the events
ResetBubblePositionTakes the bubble back to the bottom-right corner of its form and forgets where the user dragged it
IsPanelVisible: BooleanWhether the chat is on screen
OpenDocPage(APage)Opens a page of Settings.DocFolder in the documentation view of the panel
ExecuteCommand(ACommand, AArgs)Runs a slash command in the panel as if typed - any command, enabled or not
ExplainCommand(ACommand, AArgs): stringThe same answer as plain text, without the panel
ClearConversationClears the conversation, like ↺
Models: TArray<THelpChatModelInfo>The models, the one in use marked
SelectModel(AName): BooleanSwitches the model; False for an unknown name or a remote engine. The engine is the profile's: the switch holds for every assistant that shares it
Languages: TArray<THelpChatLanguage>The languages the flag of the panel offers
ActiveLanguage: THelpChatLanguageThe language the chat speaks now, never hclAuto
SelectLanguage(ALanguage): BooleanSwitches the language and reloads the panel; False when it is not offered or the engine is remote
RetryLastQuestion(AModel = '')The last question again, to another model if named
SaveConversationPdfSaves the conversation as PDF, asking where
CopyLastAnswerCopies the last answer
AttachFile(AFileName, out AError): BooleanAttaches a file, like the clip
BuildContext: THelpChatContextBuilds the context now (fires OnGetContext)
BuildTheme: THelpChatThemeThe theme that would be applied (fires OnGetTheme)
ApplyThemeRecomputes the colours and pushes them into the open page
ResolvedCaption: stringThe title actually used: Caption, or the localized default
ResolvedAssistantName: stringThe name actually used: the AssistantName of the configuration, else the property, else the localized default
AssistantIconDataUri: stringThe icon of the bubble as the data:image/png URI the page loads; empty when there is none
ApplyAssistantRetitles the own window and pushes name and icon to the panel; called for you when Caption, AssistantName, Images, ImageIndex or ImageName changes, and at activation
IsHelpViewerActive: BooleanWhether this assistant answers the help system: active, with RegisterHelpViewer
ActiveControlHasHelp: Booleanclass function — whether the focused control or a parent declares help
CurrentAssistant: TVclHelpChatAIclass function — the assistant F1 goes to now (the one of the active form, else the one whose form was active last); nil when none takes F1
ResolvedHostForm: TCustomFormThe form the assistant lives on: HostForm, else the form that owns the component, else the main form
RunSettings: THelpChatSettingsThe settings in force: the engine's while active - with the model and the language the user picked in the panel applied - else Settings. Read RunSettings.ActiveModelName, RunSettings.Provider and the key of that model here, not on Settings

Public properties ​

PropertyTypeDescription
ActionsTHelpChatActionBrokerThe registry of what the assistant may do. Available from the constructor
EngineTHelpChatEngineThe engine of the profile, while active (nil otherwise; with a remote server it exists but is not started). It is shared with the other assistants of the same profile and not owned: never free it, and read Engine.Settings - not Settings - for what the user changed in the panel
TransportIHelpChatTransportWhat serves the panel of this assistant while active: the local server or the remote client
ViewTVclHelpChatAIPanelThe chat control (the WebView2 host), wherever it is parented
OwnFormTVclHelpChatAIFormThe component's own window, when not embedded
ActiveContainerTWinControlWho is hosting the chat right now
HostFormTCustomFormForm hosting the bubble and anchoring the window, and whose activation makes this the assistant F1 goes to; nil = the form that owns the component, else Application.MainForm. When the form given here is destroyed the assistant has no form (no bubble, ResolvedHostForm is nil) until another one - or nil - is assigned. Public and not published: at design time the form of another unit is not a component of this one, so there would be nothing to choose from

Types you will meet ​

pascal
THelpChatContext = record
  UserName: string;
  ScreenName, ScreenLabel, ScreenType: string;
  HelpKeyword: string;
  HelpContext: Integer;
  FocusedControl: string;
  function DisplayName: string;   // the readable name of the screen
  function SearchHint: string;    // what the retriever searches with
end;

THelpChatTheme = record
  Name: string;
  IsDark: Boolean;
  Background, Surface, Text, Border, Accent: string;   // '#rrggbb'
  // ...derived colours, filled in automatically
  FontFamily: string;
  StyleSheet: string;   // the CSS of PanelStyleSheet
end;

Minimal example ​

pascal
uses
  System.IOUtils, HelpChatAI.Types, Vcl.HelpChatAI,
  HelpChatAI.Provider.DocSearch;   // a provider exists only if its unit is linked

procedure TMainForm.FormCreate(Sender: TObject);
begin
  HelpChatAI.Settings.Provider := 'docsearch';
  HelpChatAI.Settings.DocIndexFile := TPath.Combine(
    TPath.GetDirectoryName(ParamStr(0)), 'help-index.json');
  HelpChatAI.Settings.DocBaseUrl := 'https://help.mycompany.com/myapp/';
  HelpChatAI.Active := True;
end;

Released under the Apache License 2.0