Chapter 16: Getting help when there’s no help

When I did this I selected a DLL project from the wizard so to get the project to compile (and find ToolsAPI.pas) you need to enabled packages and use at least the following packages:

• RTL;
• VCL;
• DesignIDE.

Your project should now compile BUT you will get some warnings.

Depending upon your version of RAD Studio / Delphi the conditional compilation include file created by the wizard will not handle your version of the compiler (it only went up to XE2 not 11 – sorry couldn’t resist). You need to extend the conditions far enough to cover your compiler (the pattern should be obvious and has been explain in Conditional Compilation of Open Tools API Experts).

Below is the definition of the IOTAHelpServices from the XE7 ToolsAPI.pas file.

IOTAHelpServices = interface(IDispatch)
    ['{25F4CC12-EA93-4AEC-BC4A-DFDF427053B0}']
    procedure ShowKeywordHelp(const Keyword: WideString); safecall;
    function UnderstandsKeyword(const Keyword: WideString): WordBool; safecall;
    procedure ShowContextHelp(ContextID: Integer); safecall;
    procedure ShowTopicHelp(const Topic: WideString); safecall;
    function GetFileHelpTrait(const FileName: WideString): IOTAHelpTrait; safecall;
    function GetPersonalityHelpTrait(const Personality: WideString): IOTAPersonalityHelpTrait; safecall;
  end;

Below are my understanding of their function as there are no comments in the file (note, I only use 1 of these methods for this expert):

ShowKeywordHelp

UnderstandsKeyword

ShowContextHelp

ShowTopicHelp

GetFileHelpTrait

IOTAHelpTrait = interface(IDispatch)
    ['{DEE36173-1597-498A-A85A-C90BFCAE9B74}']
  end;

GetPersonalityHelpTrait

IOTAPersonalityHelpTrait = interface(IDispatch)
    ['{914E82DB-4123-4AA8-91D9-DB105E1FEC64}']
    procedure ShowKeywordHelp(const Keyword: WideString); safecall;
    function UnderstandsKeyword(const Keyword: WideString): WordBool; safecall;
  end;

In order to be able to first ask the IDE if it understand a Keyword/Identifier and then secondly search for that on the internet I need to get the word underneath the cursor in the IDE’s editor. To do this (see below code) I use one of the utility functions (see Chapter 5: Useful Open Tools Utility Functions) EditorAsString which returns all the text of the current editor as a string. I then put that into a string list to get it into individual lines and then see if there is a word under the column position of the cursor. If so I trace the start and end of the word and then return that word from this function. If there is no word under the cursor I return a null string.

Function TKeybindingTemplate.GetWordAtCursor: String;

Const
  strIdentChars = ['a'..'z', 'A'..'Z', '_', '0'..'9'];

Var
  SE: IOTASourceEditor;
  EP: TOTAEditPos;
  iPosition: Integer;
  sl: TStringList;

Begin
  Result := '';
  SE := ActiveSourceEditor;
  EP := SE.EditViews[0].CursorPos;
  sl := TStringList.Create;
  Try
    sl.Text := EditorAsString(SE);
    Result := sl[Pred(EP.Line)];
    iPosition := EP.Col;
    If (iPosition > 0) And (Length(Result) >= iPosition) And
      CharInSet(Result[iPosition], strIdentChars) Then
      Begin
        While (iPosition > 1) And (CharInSet(Result[Pred(iPosition)], strIdentChars)) Do
          Dec(iPosition);
        Delete(Result, 1, Pred(iPosition));
        iPosition := 1;
        While CharInSet(Result[iPosition], strIdentChars) Do
          Inc(iPosition);
        Delete(Result, iPosition, Length(Result) - iPosition + 1);
        If CharInSet(Result[1], ['0'..'9']) Then
          Result := '';
      End Else
        Result := '';
  Finally
    sl.Free;
  End;
End;

When I first implemented this expert I passed the search URL to ShellExecute to bring the search up in the default browser but like most thing I do it grew legs and now implements a dockable form with a TWebBrowser embedded in it. I’m not going to go through this implementation especially the web browser portion as this is all about OTA but I’m not going to go through the dockable form either. Why? Well that’s in the book… coming to a web site near you soon.

In essence the code gets the Keyword at the cursor as described above and if its a valid word asks the IDE if it has any help for the word. If not then the word is embedded in a search URL and passed to the dockable browser (or you could simply use ShellExecute).

Procedure TKeybindingTemplate.ProcessKeyBinding(Const Context: IOTAKeyContext;
  KeyCode: TShortcut; Var BindingResult: TKeyBindingResult);

Const
  strMsg = 'Your search URLs are misconfigured. Ensure there is a Search URL and that ' +
    'it is checked in the list in the configuration dialogue.';

Var
  strWordAtCursor : String;
  boolHandled: Boolean;

Begin
  strWordAtCursor := GetWordAtCursor;
  If strWordAtCursor <> '' Then
    Begin
      boolHandled :=
        (BorlandIDEServices As IOTAHelpServices).UnderstandsKeyword(strWordAtCursor);
      If boolHandled Then
        BindingResult := krUnhandled
      Else
        Begin
          BindingResult := krHandled;
          If (AppOptions.SearchURLIndex <= AppOptions.SearchURLs.Count - 1) And
            (AppOptions.SearchURLIndex >= 0) Then
            TfrmDockableBrowser.Execute(
              Format(AppOptions.SearchURLs[AppOptions.SearchURLIndex], [strWordAtCursor]))
          Else
            MessageDlg(strMsg, mtError, [mbOK], 0);
        End;
    End Else
      BindingResult := krUnhandled;
End;

The RAD Studio XE7 code for this article can be downloaded from the page IDE Help Helper or directly from this link.