The FMX component
TFmxHelpChatAI (unit FMX.HelpChatAI, package HelpChatAIFmx, Delphi 12 and later) is the FireMonkey twin of TVclHelpChatAI. Same engine, same page, same events: what differs is what FireMonkey itself does differently.
// uses HelpChatAI.Provider.DocSearch: a provider exists only if its unit is linked
HelpChatAI.Settings.Provider := 'docsearch';
HelpChatAI.Settings.DocIndexFile := '...help-index.json';
HelpChatAI.Active := True;Caption and AssistantName work as in the VCL: empty means the localized "Help" and "Assistant". So do Images, ImageIndex and ImageName — the bubble is round and wears the assistant icon, and the same icon appears in the header of the panel.
One thing is genuinely different, and it bites when you pass an image list of your own. In FireMonkey a name belongs to the Source collection while ImageIndex addresses the Destination one: they are two different lookups, not two ways of saying the same thing. The component keeps the two in step all the same, as the VCL one does: setting ImageIndex takes the name of the source the first layer of that destination draws, setting ImageName takes the index of the destination that draws it (-1 when none does), and the one set last decides. When drawing, the name is tried first (BitmapItemByName), then the index (Bitmap(Size, Index)).
With no image list the ten built-in icons are used, exactly as in the VCL, and the Object Inspector drops down their names.
Everything in The VCL component applies — Open, OpenWithQuestion, OpenForHelp, Close, Toggle, the bubble (dragged and remembered the same way, and kept in front with BubbleStayOnTop on Windows), Container and the OnBeforeShowHelp / OnAfterShowHelp / OnBeforeHideHelp / OnAfterHideHelp events (with a TFmxObject container instead of a TWinControl), Actions, Settings.
What is different
F1
FireMonkey has no help routing: there is no WM_HELP, no Application.HelpKeyword. The component chains the OnKeyDown of the form it lives on — your handler still runs first — and answers F1 with the current screen. That form is HostForm when set, else the form that owns the component, else Application.MainForm:
HelpChatAI.HandleF1 := True; // the default
HelpChatAI.HostForm := Self; // or leave it: the form that owns the componentEach form may have its own assistant, and F1 on a form goes to its own. Two assistants on the same form share one chained handler, so they can come and go in any order; F1 goes to one of them - the one activated first when both become active while the form loads, see which assistant answers - so set HandleF1 to False on the other to make the choice yours. For a form with none, call HandleKeyDown - of any assistant - from its OnKeyDown: the key goes to the assistant of the form the user came from (the one whose form was active last), which opens with the active form as the screen:
procedure TOrdersForm.FormKeyDown(Sender: TObject; var Key: Word;
var KeyChar: WideChar; Shift: TShiftState);
begin
MainForm.HelpChatAI.HandleKeyDown(Key, Shift); // True when it consumed F1
end;A handler assigned to the host form after the activation replaces the chain: call HandleKeyDown from it.
RegisterHelpViewer still answers System.HelpIntfs, so code that calls the help system directly reaches the assistant of the active form. One viewer serves every assistant of the process.
The screen context
Help properties live on TStyledControl in FMX, and forms do not have them. The component walks up from the focused control; the active TTabItem gives the screen label. When nothing has the focus — common in FMX — it falls back to the active tab of the first TTabControl it finds. Give your tabs a HelpKeyword and the context works the same way as in the VCL. A form that needs a keyword of its own declares it in OnGetContext, reading AContext.ScreenType (not Screen.ActiveForm, which is the chat when the user asks from it).
Colours
There are no VCL styles to follow, so the colours come from ThemeMode:
| Value | Result |
|---|---|
tmAuto (default) | the page's own defaults, following the light/dark setting of the system |
tmLight | the built-in light theme |
tmDark | the built-in dark theme |
OnGetTheme adjusts the result exactly as in the VCL — see Colours and theming.
Confirmation of actions
An action marked as needing confirmation is asked about through OnActionConfirm. With no handler, on Windows and macOS, the confirmation dialog of the library asks: FMX.HelpChatAI.ConfirmDialog, a form that follows the style of the application (the message box of TDialogService is the one of the system, and a dark style does not reach it). On a mobile platform a modal form answers in a callback later on, while a worker thread is waiting for the answer now: there, with no handler, the action is refused and the model is told so. Assign OnActionConfirm and ask the user your way:
procedure TMainFormFmx.HelpChatActionConfirm(Sender: TObject; const AName: string;
const AArgs: THelpChatActionArgs; var AAllow: Boolean);
begin
AAllow := not FReadOnlyMode; // your policy, not a dialog
end;A dialog of your own is a form implementing IFmxHelpChatConfirmDialog, registered with RegisterFmxHelpChatConfirmDialog; HelpChatActionConfirmText writes the same question as plain text, for a message box. One dialog is open at a time per assistant: a second question of the same assistant dismisses the first as No, a question of another assistant opens over it.
Attachments
Settings.Attachments.Enabled turns on the paper clip, exactly as in the VCL - the panel is the same page, and the file dialog of the embedded browser opens the same way. See Attaching documents.
Containers and the web view
A native web view is not moved from one window to another: when the container changes, the control is recreated and the page reloads. The conversation is not lost — it lives in the engine, not in the page.
Navigation outside the panel
The panel only shows the chat and the pages of Settings.DocFolder; a link that leaves it reaches OnOpenLink, else opens in the system browser. On Delphi 13 the navigation is cancelled before it starts (OnShouldLoadURL). Delphi 12 has no way to cancel a navigation, so the link is opened in the system browser and the panel returns to its own page as soon as the intruder has loaded. Links come from sanitized Markdown (http, https, mailto only), so what can appear there is an ordinary documentation page.
Dictation
There is none: the microphone button is VCL only for now. The FMX panel is the same page, so when an engine is wired to it the button will appear there too.
At design time
The component editor offers Configuration... (also a double click), Test HelpChat..., Check configuration..., Rebuild documentation index... and the link to this documentation, and Settings.Provider and ImageName get editors of their own: see the component editor, which describes both frameworks. The configuration editor is the same window as the VCL one, written with FireMonkey controls.
The component shows up in the Tool Palette of FireMonkey forms only, and the VCL one only in VCL forms. That is not automatic for a component that is a plain TComponent: each one declares its class group (GroupDescendentsWith, the way TApplicationEvents and the FireMonkey dialogs do), which is what the palette filters on.
The component editor has the verbs of the VCL one, Test HelpChat... included: the live chat in a FireMonkey form, with the panel and the native TWebBrowser your application runs. HostForm is not published, for the same reason as in the VCL.
Platforms
| Platform | State |
|---|---|
| Windows | verified (WebView2, WindowsEngine = EdgeOnly) |
| macOS, iOS, Android | the code compiles and uses the native web view, but has not been tested yet |
On mobile, remember that a local HTTP server in-process is awkward and the model API key must not be in the package: that is what the remote server is for.