Sign in Join
Wiki copytemporary

Creating IDE Help: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: Creating IDE Help

OldNewLine
1+# Overview
2+
3+The IDE can search help for various things and there are various sources in various help formats. Here is a short list to understand the complexity:
4+
5+- **FPC messages**: compiler message like *Error: Illegal enum minimum-size specifier*. The IDE has a default built-in to search for the *FPCSrcDir/compiler/msg/errore.msg file*, search the message there and show the corresponding comment. The comments contain Latex tags which are stripped. At the moment a simple MessageDlg is shown. Some notorious messages need more explanation and are manually connected to URLs.
6+- **IDE windows, dialogs and controls**:
7+- **Pascal sources**:
8+- **FPC keywords**:
9+- **FPC directives**:
10+- **IDE directives**:
11+
12+# Demos and explore
13+
14+You can see the currently installed help under **View / IDE Internals / About IDE / Help**.
15+
16+There is a test and demonstration package under **examples/idehelp/demoidehelp.lpk**. It contains example code how you can add help to the IDE.
17+
18+To show your help in the user's browser see examples/helphtml/htmlhelp1.lpi.
19+
20+To show HTML help in a LCL control see examples/htmlhelp_ipro/htmlhelpsample.lpi.
21+
22+## Help for LCL units
23+
24+Whenever the user presses F1 for an Object Inspector property or on an identifier in the source editor the IDE searches the declaration and invokes the HTML viewer for the fpdoc item. The items can be edited easily via the [[FPDoc Editor]] tool.
25+
26+You can see the state of the LCL documentation here: [[LCL Documentation Roadmap]].
27+
28+## Help for IDE windows
29+
30+This feature exists since 0.9.15.
31+
32+The help for the IDE windows (i.e. 'Object Inspector' or the 'Compiler Options') are documented in this wiki. The IDE has a mapping file *docs/IDEWindowHelpTree.xml*, which contains the paths from the various IDE forms/controls to wiki pages. This mapping file is edited via an editor that is shown at any place in the IDE via <span class="kbd">Ctrl</span>+<span class="kbd">Shift</span>+<span class="kbd">F1</span>, except for controls that catch all keys, like synedit. You can set the shortcut in the editor options -\> key mapping.
33+
34+The root page of the IDE window docs is [[Lazarus IDE]].
35+
36+### Example
37+
38+- Open the project options: Project / Project Options
39+- Open the help editor: <span class="kbd">Shift</span>+<span class="kbd">Ctrl</span>+<span class="kbd">F1</span>
40+
41+<figure>
42+<img src="HelpEditor1.png" title="HelpEditor1.png" />
43+<figcaption>HelpEditor1.png</figcaption>
44+</figure>
45+
46+- To the left, you can see all controls of the project options dialog. You can see there are also the compiler options.
47+- Select the **ProjectApplicationOptionsFrame**
48+- Click **Create Help node**. This will create a new item on the right.
49+- Check **Has Help**
50+- Check **Is a root control**. All controls on the frame should use the help on our new help page.
51+- Change the path to **Project_Options**
52+
53+<figure>
54+<img src="HelpEditorProjectOptions.png" title="HelpEditorProjectOptions.png" />
55+<figcaption>HelpEditorProjectOptions.png</figcaption>
56+</figure>
57+
58+- You can click the **Test** button and should see [[IDE Window: Project Options]] in your browser.
59+
60+### Redirect
61+
62+The TreeView in the IDE options dialog redirects the help to the help of the selected frame:
63+
64+ide/ideoptionsdlg.pas
65+
66+``` pascal
67+procedure TIDEOptionsDialog.CategoryTreeKeyDown(Sender: TObject; var Key: Word;
68+ Shift: TShiftState);
69+var
70+ Command: Word;
71+begin
72+ Command := EditorOpts.KeyMap.TranslateKey(Key,Shift,nil);
73+ if (Command=ecContextHelp) and (PrevEditor <> nil) then begin
74+ Key:=VK_UNKNOWN;
75+ ShowContextHelpForIDE(PrevEditor);
76+ end;
77+end;
78+```
79+
80+## Help for FPC keywords
81+
82+You can register a help for fpc keywords. Note: One database can handle multiple contexts, for example help for fpc keywords, help for sources and help for messages.
83+
84+``` pascal
85+uses
86+ IDEHelpIntfs, HelpIntfs, LazHelpIntf, LazHelpHTML...
87+
88+ { TSimpleFPCKeywordHelpDatabase }
89+
90+ TSimpleFPCKeywordHelpDatabase = class(THTMLHelpDatabase) // you can use any type of database you like
91+ private
92+ FKeywordPrefixNode: THelpNode;
93+ public
94+ function GetNodesForKeyword(const HelpKeyword: string;
95+ var ListOfNodes: THelpNodeQueryList; var ErrMsg: string
96+ ): TShowHelpResult; override;
97+ function ShowHelp(Query: THelpQuery; BaseNode, NewNode: THelpNode;
98+ QueryItem: THelpQueryItem;
99+ var ErrMsg: string): TShowHelpResult; override;
100+ end;
101+
102+function TSimpleFPCKeywordHelpDatabase.GetNodesForKeyword(
103+ const HelpKeyword: string; var ListOfNodes: THelpNodeQueryList;
104+ var ErrMsg: string): TShowHelpResult;
105+var
106+ KeyWord: String;
107+begin
108+ Result:=shrHelpNotFound;
109+ if (csDesigning in ComponentState) then exit;
110+ if (FPCKeyWordHelpPrefix<>'')
111+ and (LeftStr(HelpKeyword,length(FPCKeyWordHelpPrefix))=FPCKeyWordHelpPrefix) then begin
112+ // HelpKeyword starts with KeywordPrefix
113+ KeyWord:=copy(HelpKeyword,length(FPCKeyWordHelpPrefix)+1,length(HelpKeyword));
114+ // test: testfcpkeyword
115+ if KeyWord='testfcpkeyword' then begin
116+ // this help database knows this keyword
117+ // => add a node, so that if there are several possibilities the IDE can
118+ // show the user a dialog to choose
119+ // Note: In your own database you can create one dummy node or
120+ // one node per keyword or one node per group of keywords
121+ // or whatever you like.
122+ if FKeywordPrefixNode=nil then
123+ FKeywordPrefixNode:=THelpNode.CreateURL(Self,'','');
124+ FKeywordPrefixNode.Title:='Pascal keyword '+KeyWord;
125+ CreateNodeQueryListAndAdd(FKeywordPrefixNode,nil,ListOfNodes,true);
126+ Result:=shrSuccess;
127+ end;
128+ end;
129+end;
130+
131+function TSimpleFPCKeywordHelpDatabase.ShowHelp(Query: THelpQuery; BaseNode,
132+ NewNode: THelpNode; QueryItem: THelpQueryItem; var ErrMsg: string
133+ ): TShowHelpResult;
134+var
135+ KeywordQuery: THelpQueryKeyword;
136+ KeyWord: String;
137+begin
138+ Result:=shrHelpNotFound;
139+ if not (Query is THelpQueryKeyword) then exit;
140+ KeywordQuery:=THelpQueryKeyword(Query);
141+ KeyWord:=copy(KeywordQuery.Keyword,length(FPCKeyWordHelpPrefix)+1,length(KeywordQuery.Keyword));
142+ debugln(['TSimpleFPCKeywordHelpDatabase.ShowHelp Keyword=',Keyword]);
143+ // ShowURL ...
144+end;
145+
146+procedure Register;
147+begin
148+ FPCKeywordsHelpDB:=HelpDatabases.CreateHelpDatabase('NameYourHelpDB',
149+ TSimpleFPCKeywordHelpDatabase,true);
150+end;
151+```
152+
153+## Help for Messages
154+
155+This feature exists since 0.9.15 and requires the FPC sources installed locally.
156+
157+This is invoked when the user presses F1 or uses the Help menu item of the message window.
158+
159+Normally the IDE will search the errore.msg file in the FPC sources and show the comment for the message. But some messages like *unit not found* need extra help. The following describes how to do that:
160+
161+To add a wiki help page for a message, do the following:
162+
163+- Create a wiki page under [[Build messages]]
164+- Right click on messages window / Edit help
165+- This shows the editor for message additions.
166+
167+<figure>
168+<img src="AdditionalHelpForMessages.png" title="AdditionalHelpForMessages.png" />
169+<figcaption>AdditionalHelpForMessages.png</figcaption>
170+</figure>
171+
172+The items are stored in **\<lazarusdir\>/docs/additionalmsghelp.xml**.
173+
174+## Adding Kylix help
175+
176+For wow to use the Borland Help files within the IDE editor, see [[Installing Help in the IDE|Adding Kylix Help]].
177+
178+---
179+*From the Free Pascal wiki, page "Creating IDE Help", as it stood on 2020-08-22 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).*
180+Category: Help and Docs
181+Category: IDE
182+Category: Lazarus

Back to history