F1 and the screen context
The difference between a chatbot and a help assistant is that the second one knows where the user is when they ask. HelpChatAI builds that context natively, on the main thread, and hands it to the provider — the chat page never sends it, so it cannot be stale or forged.
What the context contains
| Field | Where it comes from |
|---|---|
ScreenName | Name of the form the user is working on |
ScreenLabel | caption of the active tab sheet, or of the form |
ScreenType | class name of the form |
HelpKeyword | the deepest HelpKeyword found |
HelpContext | the deepest HelpContext found (when no keyword) |
FocusedControl | Name of the focused control |
The search starts at the focused control and walks up through its parents, with the form last: a grid with its own keyword wins over the tab sheet, which wins over the form. That is how one screen can have different help for different parts of it.
The form the user is working on is the active form - unless the chat is: then it is the form the user left for the chat, with the control it keeps focused. Click the bubble on a lead window, or go back to the open chat from it, and "where am I?" is answered with the lead window, not with the main form. While the panel is open the context follows the user: moving to another form or tab and back to the chat is enough, no need to close and reopen it. It is the same form the skills work on.
What the provider actually searches with is a search hint: the HelpKeyword when there is one, otherwise the screen label. (The screen is named to the model by the keyword only when it contains a letter: a keyword like 110 is searched, and the label is what the model reads.) Class names and internal component names are never used as search terms — they would only add noise.
Declaring the help of a screen
Use the standard Delphi properties. The value that works best is the title of the page of your manual, because that is what the retriever matches against:
// VCL
LeadsTab.HelpType := htKeyword;
LeadsTab.HelpKeyword := 'Leads'; // the title of a page of the manual
// a control that only has a context id still routes F1 to the chat,
// but the number is not searched: the screen is then found by its label
OrdersForm.HelpType := htContext;
OrdersForm.HelpContext := 4040;A HelpContext number makes F1 reach the assistant, but only a HelpKeyword - or, without one, the screen label - is used to find the page. To map numbers to pages, set AContext.HelpKeyword in OnGetContext.
In FireMonkey the same properties live on TStyledControl (forms do not have them): put them on tabs and panels, and give a form its keyword in OnGetContext.
What F1 does
Two mechanisms, in this order:
- The Delphi help system. With
RegisterHelpViewer := True(the default) a viewer implementingICustomHelpViewerandIExtendedHelpVieweris registered - one for the whole process, however many assistants there are. When a control in the chain declares help, the VCL routes F1 to the help system exactly as it would to a CHM viewer, and the help system calls HelpChatAI, which hands the request to the assistant of the form that control is on.Application.HelpKeyword(...),Application.HelpContext(...)andHelpShowTableOfContentsreach it too. - The fallback. Where nothing declares help — the VCL would do nothing at all — F1 opens the chat with the current screen, if
HandleF1is True.
Which assistant answers. The one of the active form; on a form that has none, the one whose form was active last - the expert of the window the user came from; with no form active yet, the first one activated. An assistant lives on its host form: HostForm when set, else the form that owns the component, else the main form for a component on a data module. An assistant with HandleF1 (or RegisterHelpViewer) False is left out of the choice.
Two assistants on the same form. Among those that take F1, the one that comes first in the list of the active assistants answers. The list keeps them in the order they were activated, with one exception: an assistant activated while its form is already the active one goes to the front. So for two components made active while the form loads - the usual case - it is the one activated first; for two activated later, with the form in front of the user, it is the one activated last. Activating the form afterwards does not change which of the two it is. That is an order, not a choice: set HandleF1 (and RegisterHelpViewer) to False on the one that must not answer, and the choice is yours. TVclHelpChatAI.CurrentAssistant (and TFmxHelpChatAI.CurrentAssistant) answers which one F1 goes to now.
The screen described is always the active form, whoever answers: F1 on a dialog that has no assistant of its own opens the assistant of the form behind it, with the dialog as the screen.
This is why you should not hook Application.OnHelp yourself: what you declared already works, and mixing the two produces the classic double question.
Both mechanisms, one question
A key repeat, or a request that arrives twice, cannot send the same question twice: identical questions within 1.5 seconds are shown but sent once.
In FireMonkey there is no routing at all: see The FMX component.
Refining the context
OnGetContext is called every time the context is built, just before it is used. Ask AContext.ScreenName or ScreenType which form it is about, never Screen.ActiveForm: with the chat in front, that is the window of the chat.
procedure TMainForm.HelpChatGetContext(Sender: TObject; var AContext: THelpChatContext);
begin
// a screen whose meaning depends on what it is showing
if (AContext.ScreenName = 'DocumentForm') and (FDocument <> nil) then
AContext.ScreenLabel := 'Documento ' + FDocument.Kind;
// or a keyword you compute instead of declaring
if AContext.HelpKeyword = '' then
AContext.HelpKeyword := CurrentModuleHelpTopic;
end;Use it also to remove things: if a screen label contains a customer name, blank it — only the screen name, label, type and keyword ever reach a provider, but that is still your data. The label and the class name are cut to one line of at most 80 characters, without double quotes, before they enter the system prompt: a caption is often the name of a record somebody else typed.
Asking about a screen from your own code
HelpChatAI.OpenForHelp('Leads', 0); // that screen
HelpChatAI.OpenForCurrentScreen; // what F1 does
HelpChatAI.OpenWithQuestion('How do I prepare a proposal?'); // a question of yoursAnd the standard way, which goes through the help system and therefore through HelpChatAI:
Application.HelpKeyword(PageControl.ActivePage.HelpKeyword);