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
| Property | Type | Default | Description |
|---|---|---|---|
Settings | THelpChatSettings | Everything 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 | |
Active | Boolean | False | Acquires 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 |
RegisterHelpViewer | Boolean | True | Register the chat as the help viewer of the application (ICustomHelpViewer): F1 on a control with help, Application.HelpKeyword, HelpShowTableOfContents |
HandleF1 | Boolean | True | F1 opens the chat also where nothing declares help |
Caption | string | (empty) | Title of the window the chat opens in when it is not embedded. Empty = the localized "Help" / "Aiuto" |
Profile | string | (empty) | Which assistant this is: its section under "Profiles" in the configuration and the suffix of its files. Never shown. Empty = the default assistant |
AssistantName | string | (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 |
ShowBubble | Boolean | True | The round button with the assistant icon, in the bottom-right corner of the host form |
BubbleDraggable | Boolean | True | The 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) |
BubbleStayOnTop | Boolean | False | Main 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) |
Images | TCustomImageList | nil | Image list holding the bubble icon; nil uses the icons compiled into the component |
ImageIndex | TImageIndex | 0 | Bubble icon by position, kept in step with ImageName. 0 is the first built-in icon, the default assistant |
ImageName | TImageName | (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 |
VoiceEngine | THelpChatVoiceEngine | hveSystemDictation | Who dictates: hveNone (no microphone button), the dictation of Windows, or the speech recognizer |
ConfigFileName | TFileName | (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 |
ActionsEnabled | Boolean | True | Offer the registered actions to the model |
UseSharedActions | Boolean | True | Offer also the actions every assistant shares (HelpChatSharedActions); Settings.AllowedActions narrows both |
EnabledCommands | THelpChatCommands | everything but prompt and run | The slash commands the user may type. From code any command runs |
PanelStyleSheet | TFileName | (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 |
PdfStyleSheet | TFileName | (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 |
PdfHeaderFile | TFileName | (empty) | The template of the band at the top of every sheet, with its placeholders |
PdfFooterFile | TFileName | (empty) | The template of the band at the foot |
FollowVclStyle | Boolean | True | Colour the panel after the active VCL style, and follow style changes |
RememberPanelPosition | Boolean | True | Reopen the own window where the user left it, and show the bubble where it was dragged to |
Container | TWinControl | nil | Where the chat is embedded; nil = the component's own window. At design time only the controls that can hold another one are offered |
PanelWidth | Integer | 400 | Width of the own window at 96 dpi (scaled to the monitor) |
PanelHeight | Integer | 600 | Height 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
| Event | Signature | When |
|---|---|---|
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
| Method | Description |
|---|---|
Open | Opens the panel with the context of the current screen |
OpenForCurrentScreen | Opens 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 |
Close | Hides the chat (the conversation stays) |
Toggle | Open if closed, close if open |
Assign(ASource) | Copies every published property of another TVclHelpChatAI but Active and the events |
ResetBubblePosition | Takes the bubble back to the bottom-right corner of its form and forgets where the user dragged it |
IsPanelVisible: Boolean | Whether 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): string | The same answer as plain text, without the panel |
ClearConversation | Clears the conversation, like ↺ |
Models: TArray<THelpChatModelInfo> | The models, the one in use marked |
SelectModel(AName): Boolean | Switches 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: THelpChatLanguage | The language the chat speaks now, never hclAuto |
SelectLanguage(ALanguage): Boolean | Switches 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 |
SaveConversationPdf | Saves the conversation as PDF, asking where |
CopyLastAnswer | Copies the last answer |
AttachFile(AFileName, out AError): Boolean | Attaches a file, like the clip |
BuildContext: THelpChatContext | Builds the context now (fires OnGetContext) |
BuildTheme: THelpChatTheme | The theme that would be applied (fires OnGetTheme) |
ApplyTheme | Recomputes the colours and pushes them into the open page |
ResolvedCaption: string | The title actually used: Caption, or the localized default |
ResolvedAssistantName: string | The name actually used: the AssistantName of the configuration, else the property, else the localized default |
AssistantIconDataUri: string | The icon of the bubble as the data:image/png URI the page loads; empty when there is none |
ApplyAssistant | Retitles 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: Boolean | Whether this assistant answers the help system: active, with RegisterHelpViewer |
ActiveControlHasHelp: Boolean | class function — whether the focused control or a parent declares help |
CurrentAssistant: TVclHelpChatAI | class 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: TCustomForm | The form the assistant lives on: HostForm, else the form that owns the component, else the main form |
RunSettings: THelpChatSettings | The 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
| Property | Type | Description |
|---|---|---|
Actions | THelpChatActionBroker | The registry of what the assistant may do. Available from the constructor |
Engine | THelpChatEngine | The 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 |
Transport | IHelpChatTransport | What serves the panel of this assistant while active: the local server or the remote client |
View | TVclHelpChatAIPanel | The chat control (the WebView2 host), wherever it is parented |
OwnForm | TVclHelpChatAIForm | The component's own window, when not embedded |
ActiveContainer | TWinControl | Who is hosting the chat right now |
HostForm | TCustomForm | Form 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;